기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# 시작하기
이 섹션에서는 사용자 지정 AWS 변환을 설정하고 첫 번째 변환을 실행하는 방법을 설명합니다.
## 사전 조건
사용자 지정 AWS 변환을 설치하기 전에 다음이 있는지 확인합니다.
### 지원되는 플랫폼
AWS 사용자 지정 변환은 다음 운영 체제를 지원합니다.
+ **Linux** - 모든 Linux 배포에 대한 전체 지원
+ **macOS** - macOS 시스템에 대한 전체 지원
+ **Windows** - Windows 터미널 및 PowerShell을 사용하여 기본 Windows에 대한 전체 지원(Windows에서는 아직 `atx ct` 명령이 지원되지 않음)
+ **Linux용 Windows 하위 시스템(WSL)** - WSL에서 실행할 때 지원됨
### 필수 소프트웨어
+ **Node.js 22 이상** - https://nodejs.org/en/download 다운로드
+ **Git** - 변환을 실행하려면 설치되고 작업 디렉터리가 유효한 Git 리포지토리여야 합니다. 를 실행`git init; git add .; git commit -m "Initial commit"`하여 작업 디렉터리에서 Git 리포지토리를 초기화합니다.
### 네트워크 요구 사항
다음 엔드포인트에 액세스할 수 있는 인터넷 연결이 필요합니다.
+ `transform-cli.awsstatic.com`
+ `transform-custom..api.aws`
+ `*.s3.amazonaws.com`
인터넷 제한 환경에서 작업하는 경우 방화벽 규칙을 업데이트하여 이러한 URLs.
## AWS 변환 CLI 설치
권장 설치 방법은 설치 스크립트를 사용하는 것입니다. 운영 체제의 탭을 선택합니다.
** AWS 변환 CLI를 설치하려면**
1. 설치 스크립트를 실행합니다.
------
#### [ Linux and macOS ]
```
curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash
```
------
#### [ Windows (PowerShell) ]
기본 Windows에서는 PowerShell을 사용하여 Windows 터미널에서 설치 스크립트를 실행합니다.
```
irm https://transform-cli.awsstatic.com/install.ps1 | iex
```
------
1. 설치를 확인합니다.
```
atx --version
```
명령에는 AWS Transform CLI의 설치된 버전이 표시되어야 합니다.
## 인증 구성
AWS 사용자 지정 변환에는 서비스로 인증하기 위한 AWS 자격 증명이 필요합니다. 다음 방법 중 하나를 사용하여 인증을 구성합니다.
### 환경 변수
다음 환경 변수를 설정합니다.
------
#### [ Linux and macOS ]
```
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_SESSION_TOKEN=your_session_token
```
------
#### [ Windows (PowerShell) ]
```
$env:AWS_ACCESS_KEY_ID="your_access_key"
$env:AWS_SECRET_ACCESS_KEY="your_secret_key"
$env:AWS_SESSION_TOKEN="your_session_token"
```
------
`AWS_PROFILE` 환경 변수를 사용하여 프로파일을 지정할 수도 있습니다.
------
#### [ Linux and macOS ]
```
export AWS_PROFILE=your_profile_name
```
------
#### [ Windows (PowerShell) ]
```
$env:AWS_PROFILE="your_profile_name"
```
------
**참고**
PowerShell`$env:`에서 로 설정된 환경 변수는 현재 세션에만 적용됩니다. 세션 간에 유지하려면 **시스템 속성** > **환경 변수를** 통해 설정하거나를 사용합니다`[System.Environment]::SetEnvironmentVariable()`.
### AWS 자격 증명 파일
Linux 및 macOS 또는 Windows의 `~/.aws/credentials`에 있는 자격 증명 파일`%USERPROFILE%\.aws\credentials`에서 AWS 자격 증명을 구성합니다.
```
[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key
```
### IAM 권한
자격 AWS 증명에는 AWS 사용자 지정 변환 서비스를 호출할 수 있는 권한이 있어야 합니다. [`AWSTransformCustomFullAccess`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomFullAccess) AWS 관리형 정책을 IAM 사용자 또는 역할에 연결하는 것이 좋습니다. 이 정책은 계정으로 CloudWatch 지표를 내보내는 데 필요한 [서비스 연결 역할을](using-service-linked-roles.md#using-service-linked-roles-custom) 생성할 수 있는 권한을 포함하여 사용자 지정 AWS 변환에 대한 전체 액세스 권한을 제공합니다.
보다 세분화된 제어를 위해 AWS Transform 사용자 지정은 다음과 같은 AWS 관리형 정책도 제공합니다.
+ [`AWSTransformCustomExecuteTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomExecuteTransformations) - 변환을 실행할 수 있는 액세스 권한을 제공합니다.
+ [`AWSTransformCustomManageTransformations`](security-iam-awsmanpol.md#security-iam-awsmanpol-AWSTransformCustomManageTransformations) - 변환 리소스를 생성, 업데이트, 읽기 및 삭제하고 변환을 실행할 수 있는 액세스 권한을 제공합니다.
이러한 정책에 대한 자세한 내용은 [AWSAWS 변환에 대한 관리형 정책을](security-iam-awsmanpol.md) 참조하세요. 리소스 수준 권한이 있는 사용자 지정 IAM 정책은 사용자 [AWS 지정 IAM 서비스 권한 부여 변환 참조 가이드를](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awstransformcustom.html) 참조하세요.
**참고**
변환 정의는 ARNs(Amazon AWS 리소스 이름)이 있는 리소스입니다. IAM 정책을 사용하여 IAM 정책 리소스 문에 변환 ARN을 지정하여 특정 변환 또는 변환 그룹에 대한 액세스를 제어할 수 있습니다. 태그는 그룹화된 액세스 제어에 사용할 수 있습니다.
AWS IAM Identity Center는 AWS 변환에 액세스하는 데 필요하지만 CLI를 사용하는 데는 필요하지 않습니다.
## AWS 리전 구성
AWS 사용자 지정 변환은 특정 AWS 리전에서 사용할 수 있으며 표준 AWS CLI 우선 순위를 사용하여 리전 구성을 자동으로 감지합니다.
### 지원되는 리전:
AWS 변환 사용자 지정은 다음 AWS 리전에서 사용할 수 있습니다.
+ `us-east-1` (미국 동부 - 버지니아 북부)
+ `eu-central-1` (유럽 - 프랑크푸르트)
+ `eu-west-2` (유럽 - 런던)
+ `ca-central-1` (캐나다 - 중부)
+ `ap-northeast-1` (아시아 태평양 - 도쿄)
+ `ap-northeast-2` (아시아 태평양 - 서울)
+ `ap-southeast-2` (아시아 태평양 - 시드니)
+ `ap-south-1` (아시아 태평양 - 뭄바이)
### 리전 결정 방법
CLI는 이러한 소스를 우선순위에 따라 확인하여 사용할 리전을 결정합니다.
1. `AWS_REGION` 환경 변수(가장 높은 우선 순위)
1. `AWS_DEFAULT_REGION` 환경 변수
1. AWS 구성 파일에서 선택한 프로필(`AWS_PROFILE`환경 변수를 통해)
1. AWS 구성 파일의 기본 프로필
1. 구성을 찾을 수 없는 `us-east-1` 경우 기본 대체
**참고**
AWS 구성 파일은 Linux 및 macOS 또는 Windows`~/.aws/config`의 `%USERPROFILE%\.aws\config`에 있습니다.
**참고**
`ATX_CUSTOM_ENDPOINT`이 설정된 경우 리전은 엔드포인트 URL에서 추출되고 다른 모든 설정을 재정의합니다.
### 리전 설정
다음 방법 중 하나를 선택하여 리전을 구성합니다.
**옵션 1: 환경 변수(임시 사용 권장):**
------
#### [ Linux and macOS ]
```
export AWS_REGION=
```
------
#### [ Windows (PowerShell) ]
```
$env:AWS_REGION=""
```
------
**옵션 2: AWS CLI 구성(영구적 설정에 권장):**
```
aws configure set region
```
**옵션 3: 프로필별 구성:**
------
#### [ Linux and macOS ]
```
aws configure set region --profile your_profile_name
export AWS_PROFILE=your_profile_name
```
------
#### [ Windows (PowerShell) ]
```
aws configure set region --profile your_profile_name
$env:AWS_PROFILE="your_profile_name"
```
------
**옵션 4: 직접 파일 편집:**
AWS 구성 파일을 직접 편집합니다(`~/.aws/config`Linux 및 macOS의 경우 또는 Windows`%USERPROFILE%\.aws\config`의 경우).
```
[default]
region =
[profile your_profile_name]
region =
```
### 리전 구성 확인
사용자 지정에서 사용할 리전 AWS 을 확인하려면 다음을 수행합니다.
**현재 리전 설정 확인:**
```
aws configure get region
```
**환경 변수를 확인합니다.**
------
#### [ Linux and macOS ]
```
echo "AWS_REGION: $AWS_REGION"
echo "AWS_DEFAULT_REGION: $AWS_DEFAULT_REGION"
echo "AWS_PROFILE: $AWS_PROFILE"
```
------
#### [ Windows (PowerShell) ]
```
echo "AWS_REGION: $env:AWS_REGION"
echo "AWS_DEFAULT_REGION: $env:AWS_DEFAULT_REGION"
echo "AWS_PROFILE: $env:AWS_PROFILE"
```
------
**디버그 로그에서 자세한 리전 확인 보기:**
------
#### [ Linux and macOS ]
```
tail -f ~/.aws/atx/logs/debug.log
```
------
#### [ Windows (PowerShell) ]
```
Get-Content "$env:USERPROFILE\.aws\atx\logs\debug.log" -Wait -Tail 10
```
------
리전 소스를 보여주는 로그 출력 예제:
```
2026-01-07 22:34:28 [DEBUG]: Initializing FrontendServiceClient with config:
{
"endpoint": "https://transform-custom.us-east-1.api.aws",
"region": "us-east-1",
"regionSource": "AWS_REGION"
}
```
`regionSource` 필드는 리전이 파생된 위치를 보여줍니다(예: "aws-config (profile: default)", "AWS\_REGION", "default").
**중요**
리전 구성이 지원되지 않는 리전을 가리키는 경우 CLI는 구성을 지원되는 리전으로 업데이트하는 지침과 함께 명확한 오류 메시지를 표시합니다.
## 첫 번째 변환 실행
시작하는 가장 빠른 방법은 AWS관리형 변환을 사용하는 것입니다. AWS관리형 변환은 설정 없이 사용할 준비가 된 사전 구축되고 AWS검증된 변환입니다.
** AWS관리형 변환을 대화형으로 실행하려면:**
```
atx
```
그런 다음 에이전트에게 변환을 실행하도록 요청합니다.
```
Execute the AWS/java-aws-sdk-v1-to-v2 transformation on the codebase at ./my-java-project
```
**변환을 비대화형으로 실행하려면:**
```
atx custom def exec -n AWS/java-aws-sdk-v1-to-v2 -p ./my-java-project -c "mvn clean install" -x -t
```
실행 모드, 구성 옵션 및 명령 플래그에 대한 자세한 내용은 섹션을 참조하세요[명령 참조](custom-command-reference.md).
## 변환 결과 이해
변환이 완료되면 AWS 변환 사용자 지정은 결과를 설명하는 보고서를 제공합니다. 변환이 검증되지 않은 경우(예: Java 애플리케이션의 성공적인 빌드) 보고서는 추가 작업에 대한 권장 사항을 제공합니다.
대부분의 변환은 Git을 사용하여 중간 변환을 커밋하는 여러 단계로 수행됩니다. 표준 Git 명령을 사용하여 변환의 변경 사항을 검토할 수 있습니다.
```
git status
git log
git diff {{}}
```
## 사용자 지정 변환 생성
AWS관리형 변환이 요구 사항을 충족하지 않는 경우 특정 요구 사항에 맞게 사용자 지정 변환을 생성할 수 있습니다.
**사용자 지정 변환을 생성하려면**
1. 대화형 모드에서 AWS 변환 CLI를 시작합니다.
```
atx
```
1. 에이전트에게 새 변환을 생성하도록 알리고 요구 사항을 설명합니다.
1. 품질 향상을 위해 설명서 및 코드 샘플과 같은 참조 자료를 제공합니다.
1. 변환을 반복적으로 테스트하고 구체화합니다.
1. 조직의 변환 레지스트리에 게시합니다.
사용자 지정 변환 생성에 대한 자세한 지침은 섹션을 참조하세요[워크플로](custom-workflows.md).
## AWS 웹 애플리케이션 변환(선택 사항)
AWS 변환 웹 애플리케이션은 여러 리포지토리에서 대규모 변환 캠페인을 모니터링하기 위한 선택적 인터페이스입니다. AWS 변환 웹 애플리케이션을 사용하기 전에 조직의 AWS 변환에 액세스하려면 사용자 자격 증명이 활성화되어 있어야 합니다. AWS 변환 활성화에 대한 자세한 내용은 [AWS 변환 설정을 참조하세요](https://docs.aws.amazon.com/transform/latest/userguide/transform-setup.html).
** AWS 변환 웹 애플리케이션을 사용하려면:**
1. https://aws.amazon.com/transform/ 방문하여 AWS IAM Identity Center 자격 증명을 사용하여 로그인합니다.
1. AWS 변환 웹 애플리케이션에서 "사용자 지정/코드" 작업 유형을 선택합니다.
1. 에이전트에게 사용하려는 변환 정의의 이름을 알려줍니다.
1. 웹 애플리케이션은 팀과 공유할 수 있는 AWS 변환 CLI 명령을 제공합니다. 이 명령은 변환 정의를 호출하고 실행 결과를 웹 애플리케이션에 기록합니다.
1. 변환 결과를 캡처한 후 대시보드에서 통계, 시간 절약 측정값을 보고 작업 진행 상황에 대해 질문합니다.
웹 애플리케이션은 여러 코드베이스에서 변환을 중앙 집중식으로 모니터링해야 하는 엔터프라이즈 규모의 작업을 위해 설계되었습니다.
**참고**
AWS AWS 변환 웹 애플리케이션에 액세스하려면 IAM Identity Center가 필요합니다. CLI에는 IAM Identity Center가 필요하지 않으며 표준 AWS 자격 증명만 필요합니다.