# AWS CLI 버전 2의 마이그레이션 가이드
이 섹션에는 AWS CLI 버전 1을 AWS CLI 버전 2로 업데이트하기 위한 지침이 포함되어 있습니다. AWS CLI 버전 2는 AWS CLI 버전 1을 기반으로 빌드되며 커뮤니티 피드백을 바탕으로 한 기능 및 개선 사항을 포함합니다. AWS CLI 버전 2는 AWS CLI의 최신 메이저 버전이며 모든 최신 기능을 지원합니다. 버전 2에 도입된 일부 기능은 버전 1과 백포트되지 않으므로 이러한 기능에 액세스하려면 업그레이드해야 합니다.
예기치 않은 문제를 방지하려면 버전 2로 마이그레이션하기 전에 [버전 간의 차이점에 대해 알아보세요](cliv2-migration-changes.md). AWS CLI 버전 2에는 이전 버전과의 호환성을 위해 스크립트 또는 명령을 업데이트해야 할 수 있는 새로운 기능 및 변경 사항이 포함되어 있습니다.
AWS CLI 버전 1과 2는 동일한 `aws` 명령 이름을 사용합니다. 두 버전이 모두 설치되어 있는 경우 컴퓨터는 검색 경로에 있는 첫 번째 버전을 사용합니다. 이로 인해 새 버전이 설치되어 있어도 `aws` 명령 이름이 이전 AWS CLI 버전을 호출하게 될 수 있습니다.
AWS CLI 버전 2로 업데이트하려면 아래 지침 중 하나를 따릅니다.
+ 이전에 AWS CLI 버전 1을 설치한 경우 [AWS CLI 버전 1에서 AWS CLI 버전 2 설치](cliv2-migration-instructions.md)의 지침을 따르세요.
+ 이전에 AWS CLI 버전 1을 설치하지 않은 경우 [AWS CLI 시작하기](cli-chap-getting-started.md)의 지침을 따르세요.
## AWS CLI 마이그레이션 도구를 사용하여 호환성 문제 완화
AWS CLI 버전 1과 AWS CLI 버전 2 사이에는 동작 방식에 변경 사항이 있으므로 스크립트나 명령어를 업데이트해야 할 수 있습니다. 기존 스크립트가 안전하게 마이그레이션되었는지 확인하지 않고 AWS CLI 버전 2로 업그레이드하면 AWS CLI 버전 2에서 스크립트를 실행할 때 AWS 계정의 리소스가 의도치 않게 변경되는 등 예기치 않은 문제가 발생할 위험이 있습니다.
두 가지 AWS 소유 도구를 사용하여 마이그레이션 과정을 안내받을 수 있습니다. 사용하는 도구에 관계없이 [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 버전 1의 기능입니다. 이 기능을 활성화하면 실행하는 각 AWS CLI 명령이 실행 환경이 동일하다는 가정 하에 AWS CLI 버전 2에서 다른 동작을 보일 가능성이 있는지 검사됩니다. 실행된 명령이 AWS CLI 버전 2에서 다른 동작을 보일 경우, 명령 출력과 함께 경고 메시지가 표시되며, AWS CLI 버전 2에서 AWS CLI 버전 1의 동작을 유지하기 위해 취할 수 있는 조치가 제안됩니다.
업그레이드 디버그 모드를 사용하여 마이그레이션을 진행하는 주된 이유는 명령의 동작 변경 여부를 높은 정확도로 감지할 수 있기 때문입니다. [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking)에 설명된 15가지 호환성 파괴 변경 사항 중 14가지를 업그레이드 디버그 모드를 통해 감지할 수 있습니다. 이 기능의 제한 사항은 [업그레이드 디버그 모드를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드](cli-upgrade-debug-mode.md)의 [제한 사항](cli-upgrade-debug-mode.md#upgrade-mode-limitations) 섹션을 참조하세요. 반면, 업그레이드 디버그 모드 사용의 주요 단점은 출력 내용이 실행 환경 내에서만 유효하다는 점입니다. AWS CLI 버전 2로 마이그레이션한 후 환경에서 AWS CLI 구성 설정을 변경하는 경우에도 호환성 문제가 발생할 수 있으므로, 업데이트된 환경에서 업그레이드 디버그 모드를 사용하여 다시 확인해야 합니다.
### AWS CLI v1-v2 마이그레이션 도구
AWS CLI v1-v2 마이그레이션 도구는 Python 3.9 이상에서 사용할 수 있는 독립 실행형 도구입니다. 이 도구는 AWS CLI와 독립적으로 실행되는 정적 린터입니다. 이는 CLI 버전 2에서 다른 동작을 보일 수 있는 AWS CLI AWS 버전 1 명령이 포함된 bash 스크립트를 린트합니다. AWS CLI 버전 2에서 동작 방식이 다를 가능성이 있는 것으로 감지되는 대부분의 명령에 대해, 스크립트 내의 명령을 자동으로 업데이트하여 AWS CLI 버전 2에서 AWS CLI 버전 1의 동작을 유지할 수 있습니다.
AWS CLI v1-v2 마이그레이션 도구를 사용하여 마이그레이션을 진행하는 주된 이유는 스크립트를 자동으로 업데이트하여 AWS CLI 버전 2에서 AWS CLI 버전 1 동작을 유지할 수 있기 때문입니다. 이를 통해 사용자가 직접 업데이트하는 데 드는 시간과 노력을 절감할 수 있습니다. 반면 마이그레이션 도구 사용의 주요 단점은 명령의 동작 변경 여부를 감지하는 범위가 좁다는 것입니다. 이는 정적 도구이므로 런타임에 결정되는 동작의 변화를 확인하지 않습니다.
## 업그레이드 디버그 모드와 AWS CLI v1-v2 마이그레이션 도구 중에서 선택
다음 표는 업그레이드 디버그 모드와 AWS CLI v1-v2 마이그레이션 도구의 주요 차이점을 보여주며 사용 사례에 적합한 도구를 선택하는 데 도움이 될 수 있습니다.
| 업그레이드 디버그 모드 | AWS CLI v1-v2 마이그레이션 도구 |
| --- | --- |
| AWS CLI 버전 1과 AWS CLI 버전 2 간의 호환성 파괴 변경 사항 15개 중 14개를 감지합니다. | AWS CLI 버전 1과 AWS CLI 버전 2 간의 호환성 파괴 변경 사항 15개 중 7개를 감지합니다. |
| AWS CLI를 실행할 수 있는 모든 터미널 프로그램과 호환됩니다. | bash 스크립트 린팅만 지원합니다. |
| AWS CLI 버전 1, 버전 1.44.0 이상이 필요합니다. | AWS CLI와 독립적으로 실행되며 AWS CLI를 설치할 필요가 없습니다. |
| AWS CLI 버전 2에서 AWS CLI 버전 1 동작을 유지하려면 수동 수정을 수행해야 합니다. | AWS CLI 버전 2에서 동작이 다를 가능성이 있는 것으로 감지되는 대부분의 AWS CLI 버전 1 명령을 자동으로 수정합니다. |
| 감지 사항 및 제안된 수정 사항은 실행 환경(예: AWS CLI 구성)에만 적용됩니다. | 감지 사항 및 제안된 수정 사항은 환경과 무관합니다. |
| 동작 변경 여부를 테스트 중인 각 AWS CLI 명령을 실행해야 합니다. | AWS CLI 명령을 실행할 필요가 없습니다. bash 스크립트당 한 번만 실행하면 됩니다. |
| 오탐 감지를 출력하는 것으로 알려진 사례가 정확히 5건 있습니다. | 오탐 감지를 출력하는 것으로 알려진 사례가 정확히 3건 있습니다. |
다음 표는 두 마이그레이션 도구 각각에서 지원되는 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking)를 보여줍니다.
| 호환성에 영향을 미치는 주요 변경 사항 | 업그레이드 디버그 모드로 감지됨 | AWS CLI v1-v2 마이그레이션 도구로 감지됨 |
| --- | --- | --- |
| [텍스트 파일 인코딩을 설정하도록 환경 변수 추가](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 예 | 아니요 |
| [기본적으로 이진 파라미터가 base64 인코딩 문자열로 전달됨](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 예 | 예 |
| [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 예 | 예 |
| [파라미터에 대한 `http://` 또는 `https://` URL의 자동 검색 안 함](cliv2-migration-changes.md#cliv2-migration-paramfile) | 예 | 아니요 |
| [기본적으로 모든 출력에 사용되는 페이저](cliv2-migration-changes.md#cliv2-migration-output-pager) | 예 | 예 |
| [타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](cliv2-migration-changes.md#cliv2-migration-timestamp) | 예 | 아니요 |
| [변경 사항이 없는 CloudFormation 배포 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-cfn) | 예 | 예 |
| [`us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 예 | 아니요 |
| [리전 AWS STS 엔드포인트의 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 예 | 아니요 |
| [`ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 예 | 예 |
| [AWS CLI플러그인에 대한 버전 2 지원 변경](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 예 | 아니요 |
| [숨겨진 별칭 지원이 제거됨](cliv2-migration-changes.md#cliv2-migration-aliases) | 예 | 예 |
| [`api_versions` 구성 파일 설정은 지원되지 않음](cliv2-migration-changes.md#cliv2-migration-api-versions) | 예 | 아니요 |
| [AWS CLI 버전 2는 Signature v4만 사용하여 Amazon S3 요청을 인증함](cliv2-migration-changes.md#cliv2-migration-sigv4) | 예 | 아니요 |
| [AWS CLI 버전 2에서는 페이징 파라미터에 대한 일관성이 개선됨](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 예 | 예 |
| [AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함](cliv2-migration-changes.md#cliv2-migration-return-codes) | 아니요 | 아니요 |
## 이 섹션의 추가 주제
+ [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md)
+ [AWS CLI 버전 1에서 AWS CLI 버전 2 설치](cliv2-migration-instructions.md)
+ [업그레이드 디버그 모드를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드](cli-upgrade-debug-mode.md)
+ [AWS CLI v1-v2 마이그레이션 도구를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드](cli-migration-tool.md)
# AWS CLI 버전 2의 새로운 기능 및 변경 사항
이 주제에서는 AWS CLI 버전 1과 AWS CLI 버전 2 간의 새로운 기능 및 동작 변경 사항에 관해 설명합니다. 이러한 변경으로 인해 버전 1에서와 동일한 동작을 버전 2에서도 얻을 수 있도록 스크립트 또는 명령을 업데이트해야 할 수 있습니다.
**Topics**
+ [AWS CLI 버전 2의 새로운 기능](#cliv2-migration-changes-features)
+ [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](#cliv2-migration-changes-breaking)
## AWS CLI 버전 2의 새로운 기능
AWS CLI 버전 2는 AWS CLI의 최신 메이저 버전이며 모든 최신 기능을 지원합니다. 버전 2에 도입된 일부 기능은 버전 1과 백포트되지 않으므로 이러한 기능에 액세스하려면 업그레이드해야 합니다. 이러한 특성은 다음과 같습니다.
**Python 인터프리터 필요 없음**
AWS CLI 버전 2에서는 Python을 별도로 설치할 필요가 없습니다. 여기에는 임베디드 버전이 포함되어 있습니다.
**[마법사](cli-usage-wizard.md)**
AWS CLI 버전 2에서는 마법사를 사용할 수 있습니다. 마법사가 특정 명령을 구성하는 과정을 안내합니다.
**[IAM Identity Center 인증IAM Identity Center 개념튜토리얼: AWS IAM Identity Center 및 Amazon S3AWS CLI 예제](cli-configure-sso.md)**
AWS IAM Identity Center(IAM Identity Center)을 사용하는 조직의 사용자는 Active Directory 또는 기본 제공 IAM Identity Center 디렉터리에 로그인하거나 [IAM Identity Center에 연결된 다른 IdP](https://docs.aws.amazon.com/singlesignon/latest/userguide/manage-your-identity-source-idp.html)에 로그인할 수 있습니다. 그런 다음 AWS CLI 명령을 실행할 수 있는 AWS Identity and Access Management(IAM) 역할에 매핑됩니다.
**[자동 프롬프트](cli-usage-parameters-prompting.md)**
활성화된 경우 `aws` 명령을 실행할 때 명령, 파라미터 및 리소스에 대한 AWS CLI 버전 2 프롬프트를 사용할 수 있습니다.
**[AWS CLI에 대한 공식 Amazon ECR 퍼블릭 또는 Docker 이미지 실행](getting-started-docker.md)**
AWS CLI의 공식 도커 이미지는 AWS가 직접 지원하고 유지하는 격리, 이동성 및 보안을 제공합니다. 이렇게 하면 설치를 직접 관리할 필요 없이 컨테이너 기반 환경에서 AWS CLI 버전 2를 사용할 수 있습니다.
**[클라이언트 측 페이저](cli-usage-pagination.md#cli-usage-pagination-clientside)**
AWS CLI 버전 2에서는 출력에 클라이언트 측 페이저 프로그램을 사용할 수 있습니다. 기본적으로 이 기능은 켜져 있으며 운영 체제의 기본 페이저 프로그램을 통해 모든 출력을 반환합니다.
**[`aws configure import`](cli-configure-files.md#cli-config-aws_configure_import)**
AWS Management Console에서 생성된 `.csv` 보안 인증 정보를 가져옵니다. IAM 사용자 이름과 일치하는 프로파일 이름을 이용해 `.csv` 파일을 가져옵니다.
**[https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html](https://docs.aws.amazon.com/cli/latest/reference/configure/list-profiles.html)**
구성한 모든 프로파일의 이름을 나열합니다.
**[YAML 스트림 출력 형식](cli-usage-output-format.md#yaml-stream-output)**
`yaml` 및 `yaml-stream` 형식은 [YAML](https://yaml.org) 형식을 활용하는 동시에 데이터를 스트리밍하여 대용량 데이터세트를 보다 빠르게 볼 수 있도록 합니다. 전체 쿼리가 다운로드되기 전에 YAML 데이터를 보고 사용할 수 있습니다.
**[DynamoDB용 새로운 상위 수준 `ddb` 명령](https://docs.aws.amazon.com/cli/latest/reference/ddb/index.html)**
AWS CLI 버전 2에는 상위 수준 Amazon DynamoDB 명령 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/put.html) 및 [https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html](https://docs.aws.amazon.com/cli/latest/reference/api/latest/reference/ddb/select.html)가 있습니다. 이러한 명령은 DynamoDB 테이블에 항목을 배치하고 DynamoDB 테이블 또는 인덱스에서 검색하는 간단한 인터페이스를 제공합니다.
**[https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html](https://docs.aws.amazon.com/cli/latest/reference/logs/tail.html)**
AWS CLI 버전 2에는 Amazon CloudWatch Logs 그룹에 대한 로그를 추적하는 사용자 지정 `aws logs tail` 명령이 있습니다. 기본적으로 이 명령은 지난 10분 동안 연결된 모든 CloudWatch Logs 스트림의 로그를 반환합니다.
**[상위 수준 `s3` 명령에 메타데이터 지원 추가](cli-services-s3-commands.md#using-s3-commands-before-large)**
AWS CLI 버전 2에서는 상위 수준 `s3` 명령에 `--copy-props` 파라미터가 추가되었습니다. 이 파라미터를 사용하여 Amazon Simple Storage Service(Amazon S3)에 대한 추가 메타데이터 및 태그를 구성할 수 있습니다.
**[`AWS_REGION`](cli-configure-envvars.md#envvars-list-AWS_REGION)**
AWS CLI 버전 2에는 `AWS_REGION`이라는 AWS SDK 호환 환경 변수가 있습니다. 이 변수는 요청을 보낼 AWS 리전을 지정합니다. 이는 AWS CLI에서만 적용 가능한 `AWS_DEFAULT_REGION` 환경 변수를 재정의합니다.
## AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항
이 섹션에서는 AWS CLI 버전 1과 AWS CLI 버전 2 간의 모든 동작 변경 사항에 관해 설명합니다. 이러한 변경으로 인해 버전 1에서와 동일한 동작을 버전 2에서도 얻을 수 있도록 스크립트 또는 명령을 업데이트해야 할 수 있습니다.
**Topics**
+ [텍스트 파일 인코딩을 설정하도록 환경 변수 추가](#cliv2-migration-encodingenvvar)
+ [기본적으로 이진 파라미터가 base64 인코딩 문자열로 전달됨](#cliv2-migration-binaryparam)
+ [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](#cliv2-migration-s3-copy-metadata)
+ [파라미터에 대한 `http://` 또는 `https://` URL의 자동 검색 안 함](#cliv2-migration-paramfile)
+ [기본적으로 모든 출력에 사용되는 페이저](#cliv2-migration-output-pager)
+ [타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](#cliv2-migration-timestamp)
+ [변경 사항이 없는 CloudFormation 배포 처리가 개선됨](#cliv2-migration-cfn)
+ [`us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨](#cliv2-migration-s3-regional-endpoint)
+ [리전 AWS STS 엔드포인트의 기본 동작이 변경됨](#cliv2-migration-sts-regional-endpoint)
+ [`ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨](#cliv2-migration-ecr-get-login)
+ [AWS CLI플러그인에 대한 버전 2 지원 변경](#cliv2-migration-profile-plugins)
+ [숨겨진 별칭 지원이 제거됨](#cliv2-migration-aliases)
+ [`api_versions` 구성 파일 설정은 지원되지 않음](#cliv2-migration-api-versions)
+ [AWS CLI 버전 2는 Signature v4만 사용하여 Amazon S3 요청을 인증함](#cliv2-migration-sigv4)
+ [AWS CLI 버전 2에서는 페이징 파라미터에 대한 일관성이 개선됨](#cliv2-migration-skeleton-paging)
+ [AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함](#cliv2-migration-return-codes)
### 텍스트 파일 인코딩을 설정하도록 환경 변수 추가
기본적으로 [Blob](cli-usage-parameters-types.md#parameter-type-blob)의 텍스트 파일은 설치된 로캘과 동일한 인코딩을 사용합니다. AWS CLI 버전 2는 Python의 임베디드 버전을 사용하기 때문에 `PYTHONUTF8` 및 `PYTHONIOENCODING` 환경 변수는 지원되지 않습니다. 텍스트 파일의 인코딩을 로캘과 다르게 설정하려면 `AWS_CLI_FILE_ENCODING` 환경 변수를 사용합니다. 다음 예제에서는 Windows에서 `UTF-8`을 사용하여 텍스트 파일을 열도록 AWS CLI를 설정합니다.
```
AWS_CLI_FILE_ENCODING=UTF-8
```
자세한 정보는 [AWS CLI에 대한 환경 변수 구성](cli-configure-envvars.md)을 참조하세요.
### 기본적으로 이진 파라미터가 base64 인코딩 문자열로 전달됨
AWS CLI에서 일부 명령에는 [base64](https://wikipedia.org/wiki/Base64) 인코딩 문자열이 필요하고 다른 명령에는 UTF8 인코딩 바이트 문자열이 필요했습니다. AWS CLI 버전 1에서 두 개의 인코딩된 문자열 유형 간에 데이터를 전달하려면 종종 중간 처리가 필요했습니다. AWS CLI 버전 2를 사용하면 바이너리 파라미터를 보다 일관되게 처리할 수 있으므로 한 명령에서 다른 명령으로 값을 보다 안정적으로 전달할 수 있습니다.
AWS CLI 버전 2에서는 기본적으로 모든 이진 입력 및 이진 출력 파라미터를 base64 인코딩 문자열 `blobs`(이진 대용량 객체)로 전달합니다. 자세한 내용은 [Blob](cli-usage-parameters-types.md#parameter-type-blob) 섹션을 참조하세요.
AWS CLI 버전 1 동작으로 되돌리려면 `cli\$1binary\$1format` 파일 구성 또는 `--cli-binary-format` 파라미터를 사용합니다.
### 멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨
`aws s3` 네임스페이스의 AWS CLI 버전 1 명령을 사용하여 한 S3 버킷 위치에서 다른 위치로 파일을 복사하고 해당 작업에서 [멀티파트 복사](https://docs.aws.amazon.com/AmazonS3/latest/userguide/CopyingObjctsMPUapi.html)를 사용하는 경우 소스 객체의 파일 속성이 대상 객체로 복사되지 않습니다.
기본적으로 AWS CLI 버전 2의 해당 명령은 소스의 모든 태그와 일부 속성을 대상 복사본으로 전송합니다. AWS CLI 버전 1과 비교할 때 이로 인해 Amazon S3 엔드포인트에 대해 더 많은 AWS API 호출이 수행될 수 있습니다. AWS CLI 버전 2 에서 `s3` 명령의 기본 동작을 변경하려면 `--copy-props` 파라미터를 사용
자세한 내용은 [멀티파트 복사의 파일 속성 및 태그](cli-services-s3-commands.md#using-s3-commands-before-tags) 섹션을 참조하세요.
### 파라미터에 대한 `http://` 또는 `https://` URL의 자동 검색 안 함
AWS CLI 버전 2는 파라미터 값이 `http://` 또는 `https://`로 시작하는 경우 `GET` 작업을 수행하지 않으며 반환된 내용을 파라미터 값으로 사용하지 않습니다. 결과적으로 연결된 명령줄 옵션 `cli_follow_urlparam`이 AWS CLI 버전 2에서 제거됩니다.
URL을 검색하고 해당 URL의 콘텐츠를 파라미터 값으로 전달해야 하는 경우 `curl` 또는 유사한 도구를 사용하여 URL의 콘텐츠를 로컬 파일로 다운로드하는 것이 좋습니다. 그런 다음 `file://` 구문을 사용하여 해당 파일의 콘텐츠를 읽고 파라미터의 값으로 사용합니다.
예를 들어 다음 명령은 더 이상 `http://www.example.com`에서 찾은 페이지의 콘텐츠를 검색하고 해당 콘텐츠를 파라미터로 전달하지 않습니다. 대신 리터럴 텍스트 문자열 `https://example.com`을 파라미터로 전달합니다.
```
$ aws ssm put-parameter \
--value http://www.example.com \
--name prod.microservice1.db.secret \
--type String 2
```
웹 URL의 콘텐츠를 검색하여 파라미터로 사용해야 할 경우 버전 2에서 다음을 수행하면 됩니다.
```
$ curl https://my.example.com/mypolicyfile.json -o mypolicyfile.json
$ aws iam put-role-policy \
--policy-document file://./mypolicyfile.json \
--role-name MyRole \
--policy-name MyReadOnlyPolicy
```
이전의 예에서 `-o` 파라미터는 `curl`에 소스 파일과 동일한 이름으로 현재 폴더에 파일을 저장하도록 지시합니다. 두 번째 명령은 다운로드한 파일의 콘텐츠를 검색하고 해당 콘텐츠를 `--policy-document` 값으로 전달합니다.
### 기본적으로 모든 출력에 사용되는 페이저
기본적으로 AWS CLI 버전 2는 운영 체제의 기본 페이저 프로그램을 통해 모든 출력을 반환합니다. 이 프로그램은 Linux 또는 macOS에서는 [https://ss64.com/bash/less.html](https://ss64.com/bash/less.html) 프로그램이며 Windows에서는 [https://docs.microsoft.com/windows-server/administration/windows-commands/more](https://docs.microsoft.com/windows-server/administration/windows-commands/more) 프로그램입니다. 이렇게 하면 한 번에 한 페이지씩 출력을 표시함으로써 서비스에서 많은 양의 출력을 탐색할 수 있습니다.
다른 페이징 프로그램을 사용하거나 전혀 사용하지 않도록 AWS CLI 버전 2를 구성할 수 있습니다. 자세한 내용은 [클라이언트 측 페이저](cli-usage-pagination.md#cli-usage-pagination-clientside) 섹션을 참조하세요.
### 타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨
기본적으로 AWS CLI 버전 2는 모든 타임스탬프 응답 값을 [ISO 8601 형식](https://wikipedia.org/wiki/ISO_8601)으로 반환합니다. AWS CLI 버전 1에서 명령은 HTTP API 응답에 의해 반환된 형식으로 타임스탬프 값을 반환했으며 이는 서비스마다 다를 수 있습니다.
HTTP API 응답에 의해 반환된 형식으로 타임스탬프를 보려면 `config` 파일에 `wire` 값을 사용합니다. 자세한 내용은 `cli\$1timestamp\$1format` 섹션을 참조하세요.
### 변경 사항이 없는 CloudFormation 배포 처리가 개선됨
기본적으로 AWS CLI 버전 1에서 변경 사항이 없는 CloudFormation 템플릿을 배포하면 AWS CLI가 실패 오류 코드를 반환합니다. 이를 오류로 간주하지 않고 스크립트를 계속 실행하려고 할 경우 문제가 발생합니다. `0`을 반환하는 `-–no-fail-on-empty-changeset` 플래그를 추가하여 AWS CLI 버전 1에서 이 문제를 해결할 수 있습니다.
이는 일반적인 시나리오이므로 AWS CLI 버전 2에서는 배포로 인한 변경 사항이 없고 작업에서 빈 변경 세트가 반환되는 경우 기본적으로 성공적인 종료 코드 `0`이 반환됩니다.
원래 동작으로 되돌리려면 `--fail-on-empty-changeset` 플래그를 추가해야 합니다.
### `us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨
`us-east-1` 리전을 사용하도록 AWS CLI 버전 1을 구성하는 경우 AWS CLI는 `us-east-1` 리전에 물리적으로 호스트된 글로벌 `s3.amazonaws.com` 엔드포인트를 사용합니다. AWS CLI 버전 2에서는 해당 리전을 지정할 때 true 리전 엔드포인트 `s3.us-east-1.amazonaws.com`이 사용됩니다. AWS CLI 버전 2에서 글로벌 엔드포인트를 사용하려면 명령의 리전을 `aws-global`로 설정하면 됩니다.
### 리전 AWS STS 엔드포인트의 기본 동작이 변경됨
기본적으로 AWS CLI 버전 2는 모든 AWS Security Token Service(AWS STS) API 요청을 현재 구성된 AWS 리전의 리전 엔드포인트로 보냅니다.
기본적으로 AWS CLI 버전 1의 `1.42.0` 이전 릴리스는 AWS STS 요청을 전역 AWS STS 엔드포인트로 보냅니다. 버전 1에서 [https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints](https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html#cli-config-sts_regional_endpoints) 설정을 사용하여 이 기본 동작을 제어할 수 있습니다.
최신 릴리스에서 AWS CLI 버전 2로 마이그레이션하는 경우 `1.42.0` 이후 릴리스에서는 리전 엔드포인트가 기본값으로 사용됩니다. 이 동작은 변경되지 않습니다.
### `ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨
AWS CLI 버전 2에서는 `aws ecr get-login` 명령이 컨테이너 인증과의 자동 통합을 개선한 `aws ecr get-login-password` 명령으로 바뀌었습니다.
`aws ecr get-login-password` 명령을 사용하면 프로세스 목록, 셸 기록 또는 기타 로그 파일에 자격 증명이 노출되는 위험을 줄일 수 있습니다. 또한 `docker login` 명령과의 호환성을 개선하여 더 나은 자동화를 제공합니다.
이 `aws ecr get-login-password` 명령은 AWS CLI 버전 1.17.10 이상과 AWS CLI 버전 2에서 사용할 수 있습니다. 이전 `aws ecr get-login` 명령은 이전 버전과의 호환성을 위해 AWS CLI 버전 1에서 계속 사용할 수 있습니다.
`aws ecr get-login-password` 명령을 사용하면 암호를 검색하는 다음 코드를 바꿀 수 있습니다.
```
$ (aws ecr get-login --no-include-email)
```
셸 기록 또는 로그에 암호가 노출되는 위험을 줄이려면, 대신 다음 예제 명령을 사용합니다. 이 예제에서 암호는 `docker login` 옵션에 의해 password 파라미터에 지정되는 `--password-stdin` 명령으로 직접 파이프됩니다.
```
$ aws ecr get-login-password | docker login --username AWS --password-stdin MY-REGISTRY-URL
```
자세한 내용은 *AWS CLI 버전 2 참조 가이드*의 [https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html) 섹션을 참조하세요.
### AWS CLI플러그인에 대한 버전 2 지원 변경
AWS CLI 버전 2의 플러그인 지원은 전적으로 임시적이며 안정적이고 업데이트된 플러그인 인터페이스가 출시될 때까지 사용자가 AWS CLI 버전 1에서 마이그레이션하는 것을 돕기 위한 것입니다. 특정 플러그인 또는 AWS CLI 플러그인 인터페이스가 AWS CLI 버전 2의 향후 버전에서 지원될 것이라고 보장할 수는 없습니다. 플러그인을 사용하고 있는 경우, 업그레이드할 때 AWS CLI의 특정 버전으로 잠그고 플러그인의 기능을 테스트해야 합니다.
플러그인 지원을 활성화하려면 `[plugins]`에서 `~/.aws/config` 섹션을 만듭니다.
```
[plugins]
cli_legacy_plugin_path = /python3.7/site-packages
=
```
`[plugins]` 섹션에서는 `cli_legacy_plugin_path` 변수를 정의하고 해당 값을 플러그인 모듈이 상주하는 Python 사이트 패키지 경로로 설정합니다. 그런 다음 플러그인의 소스 코드가 들어 있는 Python 모듈(`plugin-module`)의 파일 이름과 플러그인(`plugin-name`)의 이름을 제공하여 플러그인을 구성할 수 있습니다. AWS CLI는 해당 `plugin-module`을 가져오고 해당 `awscli_initialize` 함수를 호출하여 각 플러그인을 로드합니다.
### 숨겨진 별칭 지원이 제거됨
AWS CLI 버전 2에서는 버전 1에서 지원된 다음과 같은 숨겨진 별칭을 더 이상 지원하지 않습니다.
다음 표의 첫 번째 열에는 AWS CLI 버전 2를 포함하여 모든 버전에서 작동하는 서비스, 명령 및 파라미터가 나와 있고, 두 번째 열에는 AWS CLI 버전 2에서 더 이상 작동하지 않는 별칭이 나와 있습니다.
| 작동하는 서비스, 명령 및 파라미터 | 폐기된 별칭 |
| --- | --- |
| cognito-identity create-identity-pool open-id-connect-provider-arns | open-id-connect-provider-ar-ns |
| storagegateway describe-tapes tape-arns | tape-ar-ns |
| storagegateway.describe-tape-archives.tape-arns | tape-ar-ns |
| storagegateway.describe-vtl-devices.vtl-device-arns | vtl-device-ar-ns |
| storagegateway.describe-cached-iscsi-volumes.volume-arns | volume-ar-ns |
| storagegateway.describe-stored-iscsi-volumes.volume-arns | volume-ar-ns |
| route53domains.view-billing.start-time | start |
| deploy.create-deployment-group.ec2-tag-set | ec-2-tag-set |
| deploy.list-application-revisions.s3-bucket | s-3-bucket |
| deploy.list-application-revisions.s3-key-prefix | s-3-key-prefix |
| deploy.update-deployment-group.ec2-tag-set | ec-2-tag-set |
| iam.enable-mfa-device.authentication-code1 | authentication-code-1 |
| iam.enable-mfa-device.authentication-code2 | authentication-code-2 |
| iam.resync-mfa-device.authentication-code1 | authentication-code-1 |
| iam.resync-mfa-device.authentication-code2 | authentication-code-2 |
| importexport.get-shipping-label.street1 | street-1 |
| importexport.get-shipping-label.street2 | street-2 |
| importexport.get-shipping-label.street3 | street-3 |
| lambda.publish-version.code-sha256 | code-sha-256 |
| lightsail.import-key-pair.public-key-base64 | public-key-base-64 |
| opsworks.register-volume.ec2-volume-id | ec-2-volume-id |
### `api_versions` 구성 파일 설정은 지원되지 않음
AWS CLI 버전 2에서는 `api_versions` 구성 파일 설정을 사용하여 이전 버전의 AWS 서비스 API 호출을 지원하지 않습니다. 모든 AWS CLI 명령은 이제 현재 엔드포엔트에서 지원하는 서비스 API의 최신 버전을 호출합니다.
### AWS CLI 버전 2는 Signature v4만 사용하여 Amazon S3 요청을 인증함
AWS CLI 버전 2는 Amazon S3 엔드포인트로 전송된 서비스 요청을 암호화 방식으로 인증하는 이전 서명 알고리즘을 지원하지 않습니다. 서명은 모든 Amazon S3 요청에서 자동으로 수행되며 [Signature Version 4 서명 프로세스](https://docs.aws.amazon.com/AmazonS3/latest/userguide/reference_aws-signing.html)만 지원됩니다. 서명 버전은 구성할 수 없습니다. 모든 Amazon S3 버킷에 사전 서명된 URL은 이제 SigV4만 사용하며 최대 만료 기간은 1주일입니다.
### AWS CLI 버전 2에서는 페이징 파라미터에 대한 일관성이 개선됨
AWS CLI 버전 1에서는 명령줄에서 페이지 매김 파라미터를 지정하면 자동 페이지 매김이 예상대로 꺼집니다. 그러나 `‐‐cli-input-json` 파라미터가 있는 파일을 사용하여 페이지 매김 파라미터를 지정할 경우 자동 페이지 매김이 꺼지지 않아 예기치 않은 출력이 발생할 수 있습니다. AWS CLI 버전 2는 파라미터를 제공하는 방법에 관계없이 자동 페이지 매김을 끕니다.
### AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함
AWS CLI 버전 2는 AWS CLI 버전 1에 비해 모든 명령에서 더 일관되고 적절한 종료 코드를 제대로 반환합니다. 종료 코드 252, 253 및 254도 추가되었습니다. 종료 코드에 대한 자세한 내용은 [AWS CLI의 명령줄 반환 코드](cli-usage-returncodes.md) 섹션을 참조하세요.
AWS CLI 버전 1이 반환 코드 값을 사용하는 방식에 대한 종속성이 있는 경우 종료 코드를 확인하여 예상 값을 얻고 있는지 확인하는 것이 좋습니다.
# AWS CLI 버전 1에서 AWS CLI 버전 2 설치
이 주제에서는 AWS CLI 버전 1에서 AWS CLI 버전 2로 마이그레이션하는 지침을 제공합니다.
AWS CLI 버전 1과 2는 동일한 `aws` 명령 이름을 사용합니다. 두 버전이 모두 설치되어 있는 경우 컴퓨터는 검색 경로에 있는 첫 번째 버전을 사용합니다. 이전에 AWS CLI 버전 1을 설치한 경우 다음 중 하나를 수행하여 AWS CLI 버전 2를 사용하는 것이 좋습니다.
+ ** 권장** – [AWS CLI 버전 1을 제거하고 AWS CLI 버전 2만 사용합니다](#cliv2-migration-instructions-migrate).
+ [두 버전을 모두 설치하려면](#cliv2-migration-instructions-side-by-side) 운영 체제의 기능을 사용하여 두 `aws` 명령 중 하나에 대해 다른 이름으로 심볼 링크(symlink) 또는 별칭을 만듭니다.
버전 1과 버전 2 간의 주요 변경 사항에 대한 자세한 내용은 [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md) 섹션을 참조하세요.
## 버전 1을 버전 2로 교체
AWS CLI 버전 1을 AWS CLI 버전 2로 교체하려면 다음 단계를 수행합니다.
**AWS CLI 버전 1을 AWS CLI 버전 2로 교체하려면**
1. [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md)에서 버전 1과 버전 2 간의 주요 변경 사항을 확인하여 마이그레이션을 위한 기존 스크립트를 준비합니다. 업그레이드 디버그 모드 기능을 사용하여 [업그레이드 디버그 모드를 사용하여 AWS CLI 버전 1을 AWS CLI 버전 2로 업그레이드](cli-upgrade-debug-mode.md)의 지침에 따라 준비 과정을 안내받을 수 있습니다.
1. [AWS CLI 버전 1 설치, 업데이트 및 제거](https://docs.aws.amazon.com/cli/v1/userguide/cli-chap-install.html)에서 사용 중인 운영 체제에 해당하는 제거 지침을 따라 AWS CLI 버전 1을 제거합니다.
1. 다음 명령을 사용하여 AWS CLI가 완전히 제거되었는지 확인합니다.
```
$ aws --version
```
출력에 따라 다음 작업 중 하나를 완료합니다.
+ **반환된 버전 없음:** AWS CLI 버전 1을 성공적으로 제거했으며 다음 단계를 진행할 수 있습니다.
+ **버전이 반환됨:** 여전히 AWS CLI 버전 1이 설치되어 있습니다. 문제 해결 단계는 [AWS CLI를 제거한 후 '`aws --version`' 명령이 버전을 반환함](cli-chap-troubleshooting.md#tshoot-uninstall-1) 섹션을 참조하세요. 버전 출력이 수신되지 않을 때까지 문제 해결 단계를 수행합니다.
1. [최신 버전의 AWS CLI 설치 또는 업데이트](getting-started-install.md)에서 사용 중인 운영 체제에 해당하는 제거 지침을 따라 AWS CLI 버전 2를 설치합니다.
## 나란히 설치
두 버전을 모두 설치하려면 운영 체제의 기능을 사용하여 두 `aws` 명령 중 하나에 대해 다른 이름으로 심볼 링크(symlink) 또는 별칭을 만듭니다.
1. [최신 버전의 AWS CLI 설치 또는 업데이트](getting-started-install.md)에서 사용 중인 운영 체제에 해당하는 제거 지침을 따라 AWS CLI 버전 2를 설치합니다.
1. 운영 체제의 기능을 사용하여 두 `aws` 명령 중 하나에 대해 다른 이름으로 심볼릭 링크 또는 별칭을 생성합니다(예: AWS CLI 버전 2에 *`aws2`* 사용). 다음은 AWS CLI 버전 2의 심볼 링크 예제입니다. *PATH*를 해당 설치 위치로 대체합니다.
------
#### [ Linux and macOS ]
Linux 및 macOS에서 [심볼 링크](https://www.linux.com/topic/desktop/understanding-linux-links/) 또는 [별칭](https://www.linux.com/topic/desktop/aliases-diy-shell-commands/)을 사용할 수 있습니다.
```
$ alias aws2='PATH'
```
------
#### [ Windows command prompt ]
[https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/doskey)Windows의 경우
```
C:\> doskey aws2=PATH
```
------
# 업그레이드 디버그 모드를 사용하여 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) 변수를 사용합니다.
# 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의 마이그레이션 가이드](cliv2-migration.md)의 [AWS CLI 마이그레이션 도구를 사용하여 호환성 문제 완화](cliv2-migration.md#using-migration-tools) 섹션을 참조하세요.
자세한 내용은 [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md)의 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking) 섹션을 참조하세요.
## 작동 방식
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 마이그레이션 도구가 지원하는 호환성 파괴 변경 및 자동 수정의 전체 목록은 [제한 사항](#migration-tool-limitations) 섹션을 참조하세요.
## 사전 조건
### Python
이 도구를 사용하려면 Python 3.9 이상이 설치되어 있어야 합니다.
올바른 Python 버전이 설치되어 있는지 확인하려면 터미널에서 다음 명령을 실행하고 출력에 3.9 이상의 Python 버전이 표시되는지 확인합니다.
```
$ python3 --version
```
이전 버전의 Python이 있거나 Python이 설치되어 있지 않은 경우 [공식 Python 다운로드 페이지](https://www.python.org/downloads/)에서 호환 버전을 다운로드할 수 있습니다.
### 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 설치](https://docs.aws.amazon.com/cli/v1/userguide/install-linux.html#install-linux-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` 파라미터를 추가하는 것으로 해석될 수 있습니다.
제안된 각 수정 사항에 대해 다음 컨트롤 중 하나를 입력할 수 있습니다.
+ 제안된 수정 사항을 수락하려면 `y`를 입력합니다.
+ 현재 수정 사항을 거부하려면 `n`를 입력합니다.
+ 동일한 유형의 모든 수정 사항을 수락하려면 `a`를 입력합니다.
+ 동일한 유형의 모든 수정 사항을 거부하려면 `r`를 입력합니다.
+ 나머지 수정 사항을 모두 수락하려면 `u`를 입력합니다.
+ 저장하고 종료하려면 `s`를 입력합니다.
+ 저장하지 않고 종료하려면 `q`를 입력합니다.
일부 조사 결과는 수정 사항 제안 없이 수동 검토 대상으로 플래그가 지정될 수 있습니다. 이러한 조사 결과를 검토하고 언급된 호환성 파괴 변경 사항의 영향을 받는지 확인해야 합니다. 이러한 조사 결과의 영향을 받는 경우 조사 결과 설명에 명시된 지침에 따라 AWS CLI 버전 2에 도입된 호환성 파괴 변경 사항을 방지하거나 그에 대비하는 데 필요한 변경을 수행해야 합니다.
## 제한 사항
AWS CLI v1-v2 마이그레이션 도구는 현재 AWS CLI 버전 2에 도입된 모든 호환성 파괴 변경 사항을 지원하지 않으며, 실제로 호환성 문제가 발생하지 않는 명령에 대해서도 호환성 파괴 변경이 감지되는 오탐 사례가 있습니다.
고객은 [AWS CLI 버전 2의 새로운 기능 및 변경 사항](cliv2-migration-changes.md)에 게시된 [AWS CLI 버전 1과 AWS CLI 버전 2 간의 주요 변경 사항](cliv2-migration-changes.md#cliv2-migration-changes-breaking) 내용을 이해하는 것이 좋습니다.
### 텍스트 기반 분석
마이그레이션 도구는 스크립트를 실행하지 않고 분석합니다. 이로 인해 AWS CLI 명령의 호환성 파괴 변경에 대한 감지가 제한됩니다. 마이그레이션 도구는 AWS CLI 명령의 텍스트만 검사할 수 있습니다. 더 이상 사용되지 않는 파라미터를 AWS CLI에 직접 전달하는 대신 변수에 저장하는 등 런타임에 발생하는 문제를 감지할 수 없습니다.
### 지원되지 않는 주요 변경 사항 감지
마이그레이션 도구의 호환성 파괴 변경에 대한 지원 범위는 다음 표에 요약되어 있습니다.
| 호환성에 영향을 미치는 주요 변경 사항 | 감지 지원 | 자동 수정 지원 |
| --- | --- | --- |
| [텍스트 파일 인코딩을 설정하도록 환경 변수 추가](cliv2-migration-changes.md#cliv2-migration-encodingenvvar) | 아니요 | 아니요 |
| [기본적으로 이진 파라미터가 base64 인코딩 문자열로 전달됨](cliv2-migration-changes.md#cliv2-migration-binaryparam) | 예 | 예 |
| [멀티파트 복사를 수행할 때 Amazon S3의 파일 속성 및 태그 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-s3-copy-metadata) | 예 | 예 |
| [파라미터에 대한 `http://` 또는 `https://` URL의 자동 검색 안 함](cliv2-migration-changes.md#cliv2-migration-paramfile) | 아니요 | 아니요 |
| [기본적으로 모든 출력에 사용되는 페이저](cliv2-migration-changes.md#cliv2-migration-output-pager) | 예 | 예 |
| [타임스탬프 출력 값이 ISO 8601 형식으로 표준화됨](cliv2-migration-changes.md#cliv2-migration-timestamp) | 아니요 | 아니요 |
| [변경 사항이 없는 CloudFormation 배포 처리가 개선됨](cliv2-migration-changes.md#cliv2-migration-cfn) | 예 | 예 |
| [`us-east-1` 리전의 리전 Amazon S3 엔드포인트 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-s3-regional-endpoint) | 아니요 | 아니요 |
| [리전 AWS STS 엔드포인트의 기본 동작이 변경됨](cliv2-migration-changes.md#cliv2-migration-sts-regional-endpoint) | 아니요 | 아니요 |
| [`ecr get-login`이 제거되고 `ecr get-login-password`로 대체됨](cliv2-migration-changes.md#cliv2-migration-ecr-get-login) | 예 | 아니요 |
| [AWS CLI플러그인에 대한 버전 2 지원 변경](cliv2-migration-changes.md#cliv2-migration-profile-plugins) | 아니요 | 아니요 |
| [숨겨진 별칭 지원이 제거됨](cliv2-migration-changes.md#cliv2-migration-aliases) | 예 | 예 |
| [`api_versions` 구성 파일 설정은 지원되지 않음](cliv2-migration-changes.md#cliv2-migration-api-versions) | 아니요 | 아니요 |
| [AWS CLI 버전 2는 Signature v4만 사용하여 Amazon S3 요청을 인증함](cliv2-migration-changes.md#cliv2-migration-sigv4) | 아니요 | 아니요 |
| [AWS CLI 버전 2에서는 페이징 파라미터에 대한 일관성이 개선됨](cliv2-migration-changes.md#cliv2-migration-skeleton-paging) | 예 | 아니요 |
| [AWS CLI 버전 2는 모든 명령에서 보다 일관된 반환 코드를 제공함](cliv2-migration-changes.md#cliv2-migration-return-codes) | 아니요 | 아니요 |