---
title: "AWS 계정 연결하기"
description: "CloudFormation을 사용해 AWS 계정을 Alpacon에 연결합니다. 시작 전에 필요한 조건과 부여할 권한을 확인하고 안내에 따라 연결을 마친 뒤 계정 상태를 검증하세요. 연결에 실패하면 오류 메시지와 점검 항목을 살펴보고 문제를 해결한 다음 다시 검증할 수 있습니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# AWS 계정 연결하기

AWS 계정을 연결하면 Alpacon이 EC2 인스턴스를 탐색하고, 선택 시 에이전트까지 설치할 수 있습니다. 설정은 AWS CloudFormation으로 계정에 IAM 역할을 생성하는 마법사로 진행됩니다.

## 시작하기 전에

- IAM 역할과 Lambda 함수를 생성하는 CloudFormation 스택을 만들 권한이 필요합니다(예: 관리자). 스택을 생성하기 전에 Quick Create 페이지에서 CloudFormation이 이름이 지정된 IAM 리소스를 만들 수 있다는 항목에 동의하세요.
- [서버 등록 토큰](/use/servers/register/tokens/)을 미리 준비하세요(마법사 진행 중에 생성할 수도 있습니다). 토큰은 온보딩된 서버가 배정될 그룹을 결정하며 에이전트 설치에 필요합니다.

## 연결 단계

**클라우드 계정** 페이지에서 **AWS 연결**을 클릭하고 마법사를 따릅니다.

1. **계정 이름 지정**: 계정의 표시 이름을 입력합니다. **AWS SSM을 통한 에이전트 원격 설치 허용** 여부를 선택하고, 사용할 **서버 등록 토큰**을 선택합니다.
2. **Quick Create URL 생성**: **AWS Console 열기**를 클릭하면 스택이 미리 채워진 상태로 AWS CloudFormation이 열립니다. 스택 이름은 계정마다 달라서 `AlpaconConnect-` 뒤에 Alpacon에서 이 계정의 ID(계정 페이지 주소 끝의 ID) 앞 8자리가 붙습니다. 그래서 같은 AWS 계정과 리전에서 두 번째 계정을 연결해도 첫 번째 스택과 이름이 겹치지 않습니다. 컨트롤 플레인 리전은 `us-east-1`입니다. AWS에서 스택을 생성합니다.
3. **연결 검증**: Alpacon 탭을 열어 둡니다. Alpacon이 CloudFormation 스택 생성 완료를 기다린 뒤 IAM 역할을 정상적으로 수임할 수 있는지 확인합니다. 표시되는 단계는 스택 제출 → 스택 생성 → IAM 역할 수임 → 연결 검증 순입니다. 검증에 실패하면 **검증 재시도**를 하거나 삭제 후 다시 시작할 수 있습니다.
4. **인스턴스 탐색**: Alpacon이 EC2 인벤토리 동기화를 시작하고 리전별로 발견된 인스턴스를 실시간으로 보여줍니다. 탐색은 일부 리전을 빠뜨린 채 끝나거나, 오류로 멈추거나, 아무 응답 없이 끝날 수도 있습니다. 어느 쪽인지는 화면에 표시되며 **다시 스캔하기**로 한 번 더 시도할 수 있습니다.

## Alpacon이 받는 권한

CloudFormation 스택은 Alpacon에 `AlpaconCrossAccountRole-` 뒤에 스택 ID(CloudFormation에 표시되는 스택 ID 끝부분의 UUID)를 붙인 이름의 역할을 부여하므로, 연결마다 고유한 역할이 생성됩니다. 이전 버전의 템플릿으로 연결한 계정은 접미사 없는 `AlpaconCrossAccountRole`을 그대로 씁니다. 이 역할의 권한은 다음과 같습니다.

- **EC2 인벤토리 조회**(필수): 모든 리전의 인스턴스, 리전, 태그를 조회합니다.
- **AWS SSM을 통한 에이전트 설치**(선택): 설치 명령을 전송해 인스턴스를 원클릭으로 온보딩합니다. 이 권한은 스택의 `EnableRemoteCommand` 매개변수로 정해지며, 스택을 만들 때 고정됩니다. 마법사에서 에이전트 설치를 허용하면 Quick Create 링크에 이 매개변수가 설정되지만, 나중에 Alpacon에서 **에이전트 원격 설치**를 켠다고 기존 스택에 권한이 추가되지는 않습니다.

연결한 뒤 이 선택을 바꾸려면 AWS에서 계정의 CloudFormation 스택을 원하는 `EnableRemoteCommand` 값으로 업데이트한 다음, Alpacon에서 권한을 다시 확인하세요. [원격 명령 권한](/integrate/cloud/accounts/#원격-명령-권한)을 참고하세요.

AWS 계정에서 CloudFormation 스택을 삭제하면 언제든 권한을 회수할 수 있습니다.

## 문제 해결

**검증 실패**: CloudFormation 스택 생성이 완료됐는지, IAM 역할의 신뢰 정책이 유지되는지 확인하세요. **검증 재시도**를 사용하거나 스택을 삭제하고 마법사를 다시 실행하세요. 권한 오류는 AWS CloudTrail에서 확인할 수 있습니다.

**에이전트 설치가 차단됨**: API 오류 코드 `cloud_remote_command_permission_missing`과 함께 설치가 거부됐다면 원인은 두 가지이며, 계정의 **AWS 스택 권한** 항목에 표시된 상태로 구분할 수 있습니다. **거부됨**이면 IAM 역할에 SSM 권한이 없는 것입니다. 대개 `EnableRemoteCommand`를 끈 채 스택을 만든 경우이므로, 스택을 업데이트해 `EnableRemoteCommand`를 `true`로 바꾼 뒤 다시 확인할 권한이 있다면 계정 페이지에서 **다시 확인**을 클릭하세요. 다른 상태라면 IAM 역할 외부의 정책이 설치를 거부한 것이므로, 해당 인스턴스와 리전에 적용되는 서비스 제어 정책(SCP), 권한 경계, 명시적 거부를 확인하세요. [원격 명령 권한](/integrate/cloud/accounts/#원격-명령-권한)을 참고하세요.

**탐색에 실패했어요**: 탐색이 끝까지 가지 못해 미처 훑지 못한 인스턴스가 빠져 있습니다. AWS가 돌려준 원인이 화면에 그대로 표시되며, 대개 IAM 역할에 권한이 빠져 있습니다. 역할을 고친 뒤 **다시 스캔하기**를 누르세요. 탐색이 끝내 되지 않으면 [서버 등록 토큰](/use/servers/register/tokens/)으로 서버를 직접 등록할 수 있습니다.

**일부 리전을 건너뛰었어요**: 탐색은 끝났지만 일부 리전을 읽지 못해, 그 리전의 인스턴스가 목록에서 빠져 있습니다. 건너뛴 리전과 이유가 화면에 함께 표시되며, **이 리전에서 접근이 거부됐어요**로 표시된 리전은 역할 수임 자체가 거부된 경우입니다. 계정에서 활성화하지 않은 리전이거나, 조직 정책(SCP 등)이 그 리전에서 역할을 막았거나, IAM 역할에 그 리전에 필요한 권한이 빠진 경우가 많습니다. 다른 이유로 건너뛴 리전은 대개 일시적이라 자연히 풀립니다. 리전을 건너뛰는 것만으로는 계정이 실패로 바뀌지 않으며, 무엇이 계정을 실패로 만드는지는 아래 **계정이 실패로 표시됨**을 참고하세요. 리전을 활성화하거나 권한을 준 뒤 **다시 스캔하기**를 누르세요.

**모든 리전에서 접근이 거부됐어요**: 탐색이 모든 리전에 도달했지만 각 리전에서 역할 수임이 거부됐습니다. 화면에는 **모든 리전에서 접근이 거부됐어요**와 함께 **이번에는 아무것도 스캔하지 못했어요. 이 상태가 계속되면 계정이 실패 상태로 바뀌어요.**가 표시됩니다. 거부가 한 번만 일어나면 계정은 실패로 바뀌지 않으며, 3회 연속 이어질 때만 실패로 바뀝니다(아래 **계정이 실패로 표시됨** 참고). 역할이나 리전의 조직 정책을 고친 뒤 **다시 스캔하기**를 누르세요.

**탐색 응답이 오지 않았어요**: 계정은 연결됐지만 탐색이 끝났다는 신호가 오지 않아, 인스턴스가 있는지 아직 알 수 없습니다. 인스턴스가 없는 계정과는 다른 상태입니다. **다시 스캔하기**를 누르세요.

**계정이 실패로 표시됨**: AWS가 역할 수임을 거부하면 계정이 실패로 바뀝니다. 거부는 검증 시점(연결 직후 첫 검증이거나 이후 **검증 다시 시도**를 사용한 검증)에 일어날 수도 있고, 탐색에서 역할 수임 자체가 거부되거나 모든 리전이 거부되거나 리전 목록 조회가 거부된 상태가 3회 연속 이어질 때 일어날 수도 있습니다. 인스턴스를 여전히 찾은 탐색은 거부 횟수를 초기화합니다. 이 상태에서는 **다시 스캔하기**가 거부되므로, 계정을 열고 실패 배너의 **검증 다시 시도**를 눌러 되돌려야 합니다. 되돌리면 실패 횟수가 초기화되고 탐색도 자동으로 다시 시작됩니다. 화면에 나온 원인을 먼저 고치지 않으면 이어지는 탐색도 같은 이유로 실패합니다. 일시적인 문제(AWS 쓰로틀링, AWS 장애, 타임아웃, Alpacon 쪽 자격 증명 문제)는 계정을 실패로 만들지 않습니다. Alpacon은 오류만 기록하고 계속 스캔하며, 연결 직후의 첫 검증만 문제가 계속될 때 몇 차례 자동으로 다시 시도한 뒤 실패로 바뀝니다.

## 관련 문서

- [계정 관리하기](/integrate/cloud/accounts/)
- [인스턴스 인벤토리](/integrate/cloud/instances/)
- [에이전트 설치하기](/integrate/cloud/install-agent/)
- [서버 등록 토큰](/use/servers/register/tokens/)

Source: https://docs.alpacax.com/ko/integrate/cloud/connect-aws/