> For the complete documentation index, see [llms.txt](https://www.analytics-docs.laplacetec.com/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.analytics-docs.laplacetec.com/guide/startguide/connect/s3.md).

# Amazon S3 연결

주문 데이터 파일을 쌓아 두는 Amazon S3 버킷을 라플라스에 연결하는 방법입니다. 액세스 키와 IAM Role 신뢰관계 두 방식, 데이터 소스 추가와 권한 확인을 안내합니다.

{% hint style="info" %}
주문 데이터 파일(CSV, Parquet)을 쌓아 두는 Amazon S3 버킷을 연결하면, 라플라스가 매일 지정한 경로의 파일을 읽어 주문 데이터로 가져와요. 라플라스는 버킷을 **읽기만** 하고 파일을 고치거나 지우지 않아요.
{% endhint %}

## 연결 방식 고르기

연결 창 위쪽에서 두 가지 방식 중 하나를 고를 수 있어요.

| 방식                | 라플라스에 건네는 것                                            | 이런 경우에 맞아요                                      |
| ----------------- | ------------------------------------------------------ | ----------------------------------------------- |
| **액세스 키**         | 버킷 읽기 권한을 가진 IAM 사용자의 Access Key ID, Secret Access Key | 빠르게 연결하고 싶을 때                                   |
| **IAM Role 신뢰관계** | 고객 계정에 만든 role 의 ARN (비밀 키는 건네지 않아요)                   | 장기 비밀 키를 외부에 넘기지 않아야 할 때, 버킷의 특정 경로만 열어 주고 싶을 때 |

**IAM Role 신뢰관계**는 장기 비밀 키를 넘기지 않고, 라플라스가 고객 계정의 role 을 잠시 빌려 쓰는 방식이에요.

## 시작 전 준비물

* 주문 데이터 파일(CSV 또는 Parquet)이 쌓이는 **S3 버킷 이름**과 **리전**. 연결 창에서 고를 수 있는 리전은 `ap-northeast-2`(서울), `ap-northeast-1`(도쿄), `us-east-1`(버지니아), `us-west-2`(오레곤)예요.
* 파일이 쌓이는 **경로(Prefix)**. 버킷 안에서 주문 파일이 들어 있는 폴더 경로예요.
* AWS 콘솔에서 IAM 사용자 또는 role 을 만들고 정책을 붙일 수 있는 권한. 이 권한이 없다면 이 문서의 **방법 2** 링크를 회사의 AWS 관리자에게 그대로 전달해 주세요. AWS 쪽 작업은 문서만 보고 따라 할 수 있게 적어 두었어요.
* 버킷 파일이 고객 관리형 KMS 키(SSE-KMS)로 암호화돼 있다면 그 **KMS 키 ARN**. S3 기본 암호화(SSE-S3)라면 필요 없어요. 어느 쪽인지는 AWS 콘솔의 S3 > 버킷 이름 > **속성** 탭 > **기본 암호화**에서 볼 수 있어요.

## 연결 창 열기

1. 왼쪽 레일의 **데이터 연결**을 누르고, **파일로 연결**에서 **S3 주문데이터**를 눌러 주세요.

   ![데이터 연결 화면의 파일로 연결 S3 주문데이터](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-940f0692a65d62ef91e9506e47b8cc31ca232a56%2Fstartguide__connect__file__s3__01.png?alt=media)
2. **S3 주문데이터 연결** 화면 머리글 오른쪽의 **데이터 연결**을 누르면 연결 창이 열려요. 이미 만든 연결은 이 화면의 연결 표에 표시돼요.

   ![S3 주문데이터 연결 화면](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-8ed888ed1203f97badceea8dafd68afba9c43e1d%2Fstartguide__connect__file__s3__02.png?alt=media)
3. 연결 창의 **연결 정보** 위쪽에서 **액세스 키** 또는 **IAM Role 신뢰관계**를 골라 주세요. 처음에는 **액세스 키**가 선택돼 있어요.

## 방법 1. 액세스 키로 연결

### 1단계. AWS 에서 읽기 전용 액세스 키 발급

AWS IAM 콘솔에서 연결용 IAM 사용자를 만들고, 아래처럼 대상 버킷의 `s3:ListBucket`, `s3:GetObject` 권한만 주는 정책을 붙인 뒤 액세스 키를 발급해 주세요. 아래 정책에서 `<버킷 이름>` 두 곳을 연결할 버킷 이름으로 바꿔 붙여 넣으면 돼요.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::<버킷 이름>"
    },
    {
      "Effect": "Allow",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::<버킷 이름>/*"
    }
  ]
}
```

{% hint style="warning" %}

* 연결할 때 라플라스가 버킷의 파일 목록을 실제로 읽어 키를 확인해요. 이 확인은 **버킷 전체 목록**을 읽으므로, 액세스 키 방식에서는 `s3:ListBucket` 을 특정 경로로 제한하지 말아 주세요. 특정 경로만 열어 주고 싶다면 **IAM Role 신뢰관계** 방식을 써 주세요.
* 파일이 고객 관리형 KMS 키(SSE-KMS)로 암호화돼 있다면, 이 IAM 사용자에게 그 키의 `kms:Decrypt` 권한도 주어야 매일 파일을 읽을 수 있어요.
  {% endhint %}

### 2단계. 연결 정보 입력

1. **연결 이름**, **S3 버킷 이름**, **리전**을 입력해 주세요.
2. **AWS 자격증명 (버킷 읽기 권한 필요)** 아래 **AWS Access Key ID**와 **AWS Secret Access Key**에 1단계에서 발급한 키를 붙여 넣어 주세요.
3. **연결 테스트 및 저장**을 눌러 주세요. 키로 버킷을 읽을 수 있으면 "데이터 연결이 생성되었습니다. 이제 소스를 추가하세요." 가 표시돼요.

   ![액세스 키 연결 정보 입력](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-fd1a9c57133ecbb8b5d49977b49cdaffcb7b16ae%2Fstartguide__connect__file__s3__03.png?alt=media)

이어서 아래 [데이터 소스 추가](#add-source)로 가져올 경로와 파일 형식을 정해 주세요.

## 방법 2. IAM Role 신뢰관계로 연결

AWS 콘솔에서 누를 곳까지 화면과 함께 [IAM Role 신뢰관계로 S3 연결](https://www.analytics-docs.laplacetec.com/guide/startguide/connect/s3/s3-role.md) 페이지에 정리했어요. 연결을 마치면 아래 **데이터 소스 추가**로 이어 가세요.

## 데이터 소스 추가 <a href="#add-source" id="add-source"></a>

연결을 만든 뒤에는 그 연결에서 가져올 경로와 파일 형식을 데이터 소스로 추가해 주세요.

1. **S3 주문데이터 연결** 화면의 연결 표에서 방금 만든 연결 행의 **데이터 소스 추가**(+)를 눌러 주세요.
2. **데이터 소스 명칭**, **경로 (Prefix)**, **파일 형식**(Parquet 또는 CSV)을 정하고 **소스 추가**를 눌러 주세요.

   * 한 데이터 소스에 여러 판매처가 섞여 있으면 명칭은 비워 두고, 판매처 구분은 컬럼맵에서 지정해 주세요.
   * **IAM Role 신뢰관계**로 연결했다면 경로는 연결할 때 입력한 경로 안에서 지정해 주세요. role 의 권한 정책이 그 경로만 열어 주기 때문이에요.

   ![데이터 소스 추가 창](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-50f63f0444feb1dcec94710131892c19b3327f12%2Fstartguide__connect__file__s3__10.png?alt=media)
3. 결과 안내를 확인해 주세요.
   * "경로에서 파일을 확인했습니다.": 바로 가져올 파일이 있어요.
   * "지정한 경로에 파일이 없습니다. 데이터가 적재되면 자동으로 동기화됩니다.": 소스는 만들어졌고, 파일이 쌓이면 가져와요.
   * "소스가 생성됐지만 경로 검증에 실패했습니다. 버킷 권한 또는 네트워크를 확인해 주세요.": 소스는 만들어졌지만 경로를 읽지 못했어요. 권한 정책의 버킷, 경로가 맞는지 확인해 주세요.
4. 소스의 **컬럼맵 설정**에서 파일의 컬럼을 라플라스 주문 컬럼에 매칭해 주세요. 매칭할 컬럼은 [주문 컬럼](https://www.analytics-docs.laplacetec.com/guide/startguide/connect/columns/order.md)에서 확인할 수 있어요.

## 매일 하는 권한 확인과 인증 끊김

라플라스는 매일 데이터를 가져오기 전에, 연결에 저장된 키 또는 role 로 각 데이터 소스 경로의 파일 목록을 읽고 내용이 있는 파일 하나의 첫 1바이트를 읽어 권한을 확인해요. 그래서 연결한 뒤에도 아래 권한이 계속 살아 있어야 해요.

* `s3:ListBucket`: 경로의 파일 목록 읽기
* `s3:GetObject`: 파일 읽기
* `kms:Decrypt`: 파일이 고객 관리형 KMS 키(SSE-KMS)로 암호화된 경우. **IAM Role 신뢰관계**에서 키 정책이 계정의 IAM 정책을 허용하지 않는 키라면 KMS 키 정책에서도 role 을 허용해야 해요.

이 확인에서 AWS 가 접근을 거절하면 연결이 **인증 끊김** 상태로 바뀌고, 데이터 수집이 멈추며, 연결을 다시 확인해 달라는 메일이 가요. 예를 들면 이런 경우예요.

* 액세스 키를 삭제, 비활성화했거나, 키나 role 에서 권한 정책을 뗐을 때
* 버킷 정책이 라플라스의 접근을 막도록 바뀌었을 때
* role 의 신뢰 정책을 지웠거나 External ID 조건이 바뀌었을 때
* KMS 키의 `kms:Decrypt` 허용이 빠졌을 때

인증이 끊긴 연결은 연결 표에서 **데이터 소스 추가**를 누를 수 없고 "재인증이 필요합니다." 가 표시돼요.

### 다시 연결하기

* **AWS 쪽 설정을 되돌리면 자동으로 복구돼요.** 권한 정책, 버킷 정책, 신뢰 정책, KMS 키 정책을 원래대로 고쳐 두면, 다음 날 권한 확인이 통과하면서 연결이 정상 상태로 돌아오고 수집이 다시 시작돼요.
* 액세스 키를 **새 키로 바꿔야** 한다면 채널톡으로 문의해 주세요. 같은 버킷으로 새 연결을 만들면 "이 버킷으로 이미 연결이 있습니다." 안내가 표시돼요.

## 자주 발생하는 오류

### 액세스 키 방식

* **"AWS 인증에 실패했습니다."**
  * 원인: 키로 버킷의 파일 목록을 읽지 못했어요. 키 값이 틀렸거나, 키가 비활성 상태이거나, 키에 버킷 전체의 `s3:ListBucket` 권한이 없거나, 버킷 이름이 실제와 다를 때 표시돼요.
  * 조치: 키를 다시 복사해 붙여 넣고, 버킷 이름을 확인해 주세요. `s3:ListBucket` 을 특정 경로로 제한했다면 제한을 풀어 주세요.
* **"이 버킷으로 이미 연결이 있습니다. 목록의 기존 연결에서 '소스 추가'를 사용하세요."**
  * 원인: 같은 버킷으로 만든 연결이 이미 있어요.
  * 조치: 연결 표의 기존 연결에서 **데이터 소스 추가**로 경로를 더해 주세요.

### IAM Role 신뢰관계 방식

[IAM Role 신뢰관계로 S3 연결](https://www.analytics-docs.laplacetec.com/guide/startguide/connect/s3/s3-role.md) 의 **자주 발생하는 오류**를 봐 주세요.

## 연결 해제

연결 표에서 연결 행의 ⋯ 메뉴로 연결을 삭제할 수 있어요.

* 연결을 삭제하면 그 연결로 라플라스에 가져온 데이터도 함께 삭제돼요.
* S3 버킷의 원본 파일은 그대로 남아요. 라플라스는 버킷을 읽기만 해요.
* 더 이상 쓰지 않는다면 AWS 쪽에서 연결용 IAM 사용자의 액세스 키나 role 도 정리해 주세요.

## 전담 매니저에게 요청하기

S3 데이터 연결에 어려움이 있으신가요?

하단의 문의하기 혹은 홈페이지의 채팅 상담을 통해 문의하세요. 담당 매니저가 도움을 드리도록 하겠습니다.

> 💬 [채팅으로 문의하기](https://laplacetec.channel.io/lounge)
>
> 💬 [홈페이지에서 문의하기](https://www.analytics.laplacetec.com/contact)

**이메일 문의:** [**product@laplacetec.com**](mailto:product@laplacetec.com)
