For the complete documentation index, see llms.txt. This page is also available as Markdown.

Amazon S3 연결

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

연결 방식 고르기

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

방식
라플라스에 건네는 것
이런 경우에 맞아요

「액세스 키」

버킷 읽기 권한을 가진 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 주문데이터
  2. 「S3 주문데이터 연결」 화면 머리글 오른쪽의 「데이터 연결」을 누르면 연결 창이 열려요. 이미 만든 연결은 이 화면의 연결 표에 표시돼요.

    S3 주문데이터 연결 화면
  3. 연결 창의 「연결 정보」 위쪽에서 「액세스 키」 또는 「IAM Role 신뢰관계」를 골라 주세요. 처음에는 「액세스 키」가 선택돼 있어요.

방법 1. 액세스 키로 연결

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

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

2단계. 연결 정보 입력

  1. 「연결 이름」, 「S3 버킷 이름」, 「리전」을 입력해 주세요.

  2. 「AWS 자격증명 (버킷 읽기 권한 필요)」 아래 「AWS Access Key ID」와 「AWS Secret Access Key」에 1단계에서 발급한 키를 붙여 넣어 주세요.

  3. 「연결 테스트 및 저장」을 눌러 주세요. 키로 버킷을 읽을 수 있으면 "데이터 연결이 생성되었습니다. 이제 소스를 추가하세요." 가 표시돼요.

    액세스 키 연결 정보 입력

이어서 아래 데이터 소스 추가로 가져올 경로와 파일 형식을 정해 주세요.

방법 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 신뢰관계 연결 정보 입력

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

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

  • 「신뢰할 주체 (Principal ARN)」: 고객 role 을 빌려 쓸 라플라스 쪽 주체예요.

  • 「신뢰 정책 (Trust policy, ExternalId 임시값 0000)」

  • 「권한 정책 (Permission policy)」

role 생성 정보 신뢰할 주체와 신뢰 정책, 권한 정책

두 정책은 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 발급
KMS 키 설정 안내

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

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

    발급된 External ID 와 최종 신뢰 정책
  2. AWS 콘솔에서 role 의 신뢰 정책을 「최종 신뢰 정책 (Trust policy, 교체용)」으로 교체해 주세요. 임시값 0000 이 남아 있으면 라플라스가 role 을 빌려 쓸 수 없어요.

  3. 연결 창에서 「연결 테스트」를 눌러 주세요. 라플라스가 실제로 role 을 빌려 경로의 파일 목록을 읽고, 파일이 있으면 하나를 읽어 봐요.

    • "지정한 경로의 파일을 읽을 수 있는 것까지 확인했습니다." 가 보이면 읽기 권한까지 확인된 거예요.

    • "지정한 경로에 파일이 아직 없어 읽기 권한은 확인하지 못했습니다." 가 보이면 파일 읽기는 아직 확인되지 않은 상태예요. 파일이 쌓이면 매일 수집 전에 다시 확인해요.

  4. "연결 테스트에 성공했습니다." 가 표시되면 「연결 완료」를 눌러 주세요.

    연결 테스트 성공과 연결 완료
  • 처음부터 다시 하고 싶다면 「발급 취소」를 눌러 주세요. 발급한 External ID 가 버려지고, 다시 진행하면 새 External ID 를 받아요. AWS 쪽 role 의 신뢰 정책도 새 값으로 다시 교체해 주세요.

  • External ID 를 발급받고 연결 테스트를 통과하기 전에 72시간이 지나면, 다시 진행할 때 External ID 가 새로 발급되고 "이전에 발급한 값이 만료되어 새로 발급했습니다. 아래 값으로 신뢰 정책을 다시 저장해 주세요." 가 표시돼요. 새 값으로 신뢰 정책을 다시 교체해 주세요.

데이터 소스 추가

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

  1. 「S3 주문데이터 연결」 화면의 연결 표에서 방금 만든 연결 행의 「데이터 소스 추가」(+)를 눌러 주세요.

  2. 「데이터 소스 명칭」, 「경로 (Prefix)」, 「파일 형식」(Parquet 또는 CSV)을 정하고 「소스 추가」를 눌러 주세요.

    • 한 데이터 소스에 여러 판매처가 섞여 있으면 명칭은 비워 두고, 판매처 구분은 컬럼맵에서 지정해 주세요.

    • 「IAM Role 신뢰관계」로 연결했다면 경로는 연결할 때 입력한 경로 안에서 지정해 주세요. role 의 권한 정책이 그 경로만 열어 주기 때문이에요.

    데이터 소스 추가 창
  3. 결과 안내를 확인해 주세요.

    • "경로에서 파일을 확인했습니다.": 바로 가져올 파일이 있어요.

    • "지정한 경로에 파일이 없습니다. 데이터가 적재되면 자동으로 동기화됩니다.": 소스는 만들어졌고, 파일이 쌓이면 가져와요.

    • "소스가 생성됐지만 경로 검증에 실패했습니다. 버킷 권한 또는 네트워크를 확인해 주세요.": 소스는 만들어졌지만 경로를 읽지 못했어요. 권한 정책의 버킷 · 경로가 맞는지 확인해 주세요.

  4. 소스의 「컬럼맵 설정」에서 파일의 컬럼을 라플라스 주문 컬럼에 매칭해 주세요. 매칭할 컬럼은 주문 컬럼에서 확인할 수 있어요.

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

라플라스는 매일 데이터를 가져오기 전에, 연결에 저장된 키 또는 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 데이터 연결에 어려움이 있으신가요?

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

💬 채팅으로 문의하기

💬 홈페이지에서 문의하기

이메일 문의: product@laplacetec.com

마지막 업데이트