> 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 을 만들고 정책을 붙일 수 있는 권한
* 버킷 파일이 고객 관리형 KMS 키(SSE-KMS)로 암호화돼 있다면 그 **KMS 키 ARN**. S3 기본 암호화(SSE-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 콘솔을 오가며 세 단계로 진행돼요. External ID 를 발급받은 뒤 연결 창을 닫아도(「취소」) 발급한 값은 남아 있어요. 같은 버킷 · 경로와 같은 role ARN 으로 다시 진행하면 이미 발급받은 External ID 를 그대로 받아요.

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

1. 「IAM Role 신뢰관계」를 고른 뒤 「연결 이름」, 「S3 버킷 이름」, 「리전」을 입력해 주세요.
2. 「경로 (Prefix)」에 파일이 쌓이는 경로를 입력해 주세요. 입력한 경로에만 읽기 권한을 주는 정책을 안내해 드려요. 비우면 버킷 전체예요.
3. 파일이 고객 관리형 KMS 키(SSE-KMS)로 암호화돼 있다면 「KMS 키 ARN (선택)」에 키 ARN 을 입력해 주세요. S3 기본 암호화(SSE-S3)라면 비워 두세요.
4. 「role 생성 정보 받기」를 눌러 주세요.

   ![IAM Role 신뢰관계 연결 정보 입력](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-a428e8e8e7b6905469e69b8abce61f33e241b5d3%2Fstartguide__connect__file__s3__04.png?alt=media)

### 2단계. AWS 콘솔에서 role 만들기

연결 창에 role 을 만드는 데 필요한 세 가지가 표시돼요. 각 값 옆의 복사 버튼으로 복사할 수 있어요.

* 「신뢰할 주체 (Principal ARN)」: 고객 role 을 빌려 쓸 라플라스 쪽 주체예요.
* 「신뢰 정책 (Trust policy, ExternalId 임시값 0000)」
* 「권한 정책 (Permission policy)」

![role 생성 정보 신뢰할 주체와 신뢰 정책, 권한 정책](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-42bb846eacb45bb382625fc72cdd99bd067e332d%2Fstartguide__connect__file__s3__05.png?alt=media)

두 정책은 1단계에서 입력한 버킷 · 경로 · KMS 키에 맞춰 연결 창이 만들어 드려요. 직접 작성하거나 고치지 말고, **연결 창의 복사 버튼으로 복사한 내용을 그대로** 붙여 넣어 주세요.

* 신뢰 정책: 「신뢰할 주체 (Principal ARN)」만 이 role 을 빌려 쓸 수 있게 하고, External ID 가 맞을 때만 허용해요. 지금은 External ID 자리에 임시값 `0000` 이 들어 있고, 3단계에서 발급된 값으로 바꿔요.
* 권한 정책: 입력한 버킷의 파일 목록 보기(`s3:ListBucket`)와 파일 읽기(`s3:GetObject`)만 허용해요. 경로를 입력했다면 그 경로 안으로만 좁혀지고, 비웠다면 버킷 전체예요. KMS 키 ARN 을 입력했다면 그 키 하나에 대한 복호화(`kms:Decrypt`)가 함께 들어가요.

AWS IAM 콘솔에서 아래 순서로 role 을 만들어 주세요.

1. 새 role 을 만들고, 신뢰 정책(Trust policy)에 연결 창의 「신뢰 정책 (Trust policy, ExternalId 임시값 0000)」을 그대로 붙여 넣어 주세요.
2. 그 role 에 연결 창의 「권한 정책 (Permission policy)」을 붙여 주세요.
3. 만든 role 의 ARN 을 복사해 연결 창의 「생성한 Role ARN」에 붙여 넣고 「External ID 발급」을 눌러 주세요. Role ARN 은 IAM 콘솔에서 만든 role 의 요약 화면에 표시돼요.

   ![생성한 Role ARN 입력 후 External ID 발급](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-7ffdf5bb44a585b89f378c3ac6322211fd3f6644%2Fstartguide__connect__file__s3__06.png?alt=media)

{% hint style="warning" %}
KMS 키 ARN 을 입력했다면 연결 창에 「KMS 키 설정」 안내가 함께 표시돼요. 입력한 KMS 키로 암호화된 파일을 읽으려면 아래 두 가지가 **모두** 필요해요.

1. role 의 권한 정책에서 이 키에 대한 `kms:Decrypt` 를 허용해 주세요. (위 권한 정책에 이미 들어 있어요.)
2. AWS KMS 콘솔에서 이 키의 키 정책(Key policy)에 role 을 주체(Principal)로 추가하고 `kms:Decrypt` 를 허용해 주세요.
   {% endhint %}

![KMS 키 설정 안내](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-9b459ed3cb6b05d63c37ba3d5970b084920c9084%2Fstartguide__connect__file__s3__07.png?alt=media)

### 3단계. 신뢰 정책 교체 후 연결 테스트

1. 「External ID 발급」을 누르면 이 연결 전용 「External ID」와 「최종 신뢰 정책 (Trust policy, 교체용)」이 표시돼요. 최종 신뢰 정책은 2단계의 신뢰 정책에서 `"sts:ExternalId"` 값만 발급된 External ID 로 바뀐 것이에요.

   ![발급된 External ID 와 최종 신뢰 정책](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-50a1aa6cf73fd9eed6bf19877a77270951f5d02e%2Fstartguide__connect__file__s3__08.png?alt=media)
2. AWS 콘솔에서 role 의 신뢰 정책을 「최종 신뢰 정책 (Trust policy, 교체용)」으로 **교체**해 주세요. 임시값 `0000` 이 남아 있으면 라플라스가 role 을 빌려 쓸 수 없어요.
3. 연결 창에서 「연결 테스트」를 눌러 주세요. 라플라스가 실제로 role 을 빌려 경로의 파일 목록을 읽고, 파일이 있으면 하나를 읽어 봐요.
   * "지정한 경로의 파일을 읽을 수 있는 것까지 확인했습니다." 가 보이면 읽기 권한까지 확인된 거예요.
   * "지정한 경로에 파일이 아직 없어 읽기 권한은 확인하지 못했습니다." 가 보이면 파일 읽기는 아직 확인되지 않은 상태예요. 파일이 쌓이면 매일 수집 전에 다시 확인해요.
4. "연결 테스트에 성공했습니다." 가 표시되면 「연결 완료」를 눌러 주세요.

   ![연결 테스트 성공과 연결 완료](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-3267c1d10a68f5511ad4eb1447db17afa98d3aa4%2Fstartguide__connect__file__s3__09.png?alt=media)

{% hint style="info" %}

* 처음부터 다시 하고 싶다면 「발급 취소」를 눌러 주세요. 발급한 External ID 가 버려지고, 다시 진행하면 새 External ID 를 받아요. AWS 쪽 role 의 신뢰 정책도 새 값으로 다시 교체해 주세요.
* External ID 를 발급받고 연결 테스트를 통과하기 전에 72시간이 지나면, 다시 진행할 때 External ID 가 새로 발급되고 "이전에 발급한 값이 만료되어 새로 발급했습니다. 아래 값으로 신뢰 정책을 다시 저장해 주세요." 가 표시돼요. 새 값으로 신뢰 정책을 다시 교체해 주세요.
  {% endhint %}

## 데이터 소스 추가 <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. 소스의 「컬럼맵 설정」에서 파일의 컬럼을 라플라스 주문 컬럼에 매칭해 주세요. 매칭할 컬럼은 [주문 컬럼](/guide/startguide/connect/columns/order.md)에서 확인할 수 있어요.

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

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

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

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

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

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

### 다시 연결하기

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

## 자주 발생하는 오류

### 액세스 키 방식

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

### IAM Role 신뢰관계 방식

* **"role 을 빌려오지 못했습니다. 신뢰 정책과 External ID 조건, role ARN 을 확인해 주세요."**
  * 원인: 라플라스가 role 을 빌려 쓰지 못했어요. 신뢰 정책을 최종 신뢰 정책으로 교체하지 않아 `0000` 이 남아 있거나, 「신뢰할 주체 (Principal ARN)」가 다르거나, 입력한 role ARN 이 실제 role 과 다를 때 표시돼요.
  * 조치: role 의 신뢰 정책을 연결 창의 「최종 신뢰 정책 (Trust policy, 교체용)」으로 통째로 교체하고 다시 「연결 테스트」를 눌러 주세요.
* **"role 에 버킷 읽기 권한이 없습니다. 권한 정책이 제대로 붙었는지 확인해 주세요."**
  * 원인: role 은 빌렸지만 버킷 파일 목록이나 파일을 읽지 못했어요.
  * 조치: 연결 창의 「권한 정책 (Permission policy)」이 role 에 붙어 있는지, 버킷 정책이 접근을 막지 않는지 확인해 주세요.
* **"KMS 키로 암호화된 파일을 복호화하지 못했습니다. role 의 권한 정책에 kms:Decrypt 를 추가하고, KMS 키 정책에 이 role 을 허용해 주세요."**
  * 원인: 파일이 KMS 키로 암호화돼 있는데 role 이 그 키로 복호화할 수 없어요.
  * 조치: 위 「KMS 키 설정」의 두 가지를 모두 해 주세요. 1단계에서 KMS 키 ARN 을 비워 두었다면, 연결 창을 닫고 같은 버킷 · 경로 · role ARN 에 KMS 키 ARN 을 넣어 다시 진행한 뒤 새로 표시되는 권한 정책을 role 에 붙여 주세요.
* **"연결 테스트 중에 연결 설정이 바뀌었습니다. 연결 테스트를 다시 실행해 주세요."**
  * 원인: 연결 테스트를 하는 사이 같은 연결의 External ID 나 설정이 바뀌었어요(다른 창에서 다시 진행한 경우 등).
  * 조치: 연결 창에 지금 표시된 External ID 로 신뢰 정책을 확인한 뒤 「연결 테스트」를 다시 눌러 주세요.
* **"이전 단계를 먼저 완료해 주세요."**
  * 원인: 앞 단계가 끝나지 않았거나, 이 버킷 · 경로에 이미 다른 role ARN 으로 External ID 를 발급받았어요.
  * 조치: 다른 role 로 바꾸려면 「발급 취소」 후 처음부터 진행해 주세요.
* **"신뢰관계 설정을 준비하지 못했습니다. 잠시 후 다시 시도해 주세요."**
  * 원인: 라플라스 쪽에서 일시적으로 연결 정보를 준비하지 못했어요.
  * 조치: 잠시 후 다시 시도해 주세요. 계속되면 채널톡으로 문의해 주세요.

## 연결 해제

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

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

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

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

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

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

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