> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ones1ght.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon S3 연결

> 대용량 파일을 S3에서 직접 읽도록 연결하세요

## S3 연결이란?

브라우저로 올리기 어려운 대용량 파일을 Amazon S3 버킷에 두면, OneSight가 조회 시점에 해당 파일을 직접 읽습니다. 파일을 복사해 보관하지 않으므로 원본을 교체하면 다음 조회부터 바로 반영됩니다.

<Note>
  데이터소스 등록은 **관리자(Admin)** 권한이 있는 사용자만 할 수 있습니다. AWS 쪽 작업(1단계)은 해당 버킷을 관리하는 담당자가 진행해야 합니다.
</Note>

## 준비물

* 연결할 **버킷 이름**과 **리전** (예: `ap-northeast-2`)
* 아래 두 가지 인증 방식 중 하나를 설정할 수 있는 AWS 권한

## 인증 방식 두 가지

| 방식             | 설명                                                                     |
| -------------- | ---------------------------------------------------------------------- |
| **역할 위임** (권장) | 고객사 AWS 계정에 읽기 전용 역할을 만들고 OneSight에 사용을 위임합니다. **장기 액세스 키를 넘기지 않습니다.** |
| **액세스 키**      | 읽기 전용 액세스 키와 시크릿 키를 발급해 입력합니다. 설정이 더 간단합니다.                            |

<Note>
  S3 호환 스토리지(MinIO·Cloudflare R2 등)는 역할 위임을 지원하지 않습니다. 이 경우 **액세스 키** 방식을 사용하세요.
</Note>

## 1단계: 읽기 전용 권한 준비 (AWS)

OneSight가 필요로 하는 권한은 아래 두 가지뿐입니다. 파일을 올리거나 지우는 권한은 사용하지 않으므로 부여하지 마세요.

| 권한              | 용도               |
| --------------- | ---------------- |
| `s3:ListBucket` | 폴더와 파일 목록을 보여줍니다 |
| `s3:GetObject`  | 선택한 파일의 내용을 읽습니다 |

<Steps>
  <Step title="정책 만들기">
    AWS 콘솔에서 **IAM → 정책 → 정책 생성**으로 이동한 뒤 **JSON** 탭을 선택하고 아래 내용을 붙여넣습니다.
    `my-bucket` 두 곳을 실제 버킷 이름으로 바꾸세요.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "OneSightListBucket",
          "Effect": "Allow",
          "Action": ["s3:ListBucket"],
          "Resource": "arn:aws:s3:::my-bucket"
        },
        {
          "Sid": "OneSightReadObjects",
          "Effect": "Allow",
          "Action": ["s3:GetObject"],
          "Resource": "arn:aws:s3:::my-bucket/*"
        }
      ]
    }
    ```

    두 항목의 형태가 다른 것은 의도된 것입니다. 목록 조회는 **버킷 자체**에, 파일 읽기는 **버킷 안의 객체**(`/*`)에 적용됩니다.

    정책 이름은 구분하기 쉽게 `onesight-readonly` 등으로 지정합니다.
  </Step>
</Steps>

이 정책을 **누구에게 연결하느냐**가 인증 방식에 따라 갈립니다. 아래에서 선택한 방식만 진행하세요.

### 역할 위임 방식 (권장)

<Steps>
  <Step title="OneSight 화면에서 값 두 개 확인">
    콘솔에서 **데이터소스 → 추가 → 스토리지 → Amazon S3**를 연 뒤 인증 방식을 **역할 위임**으로 바꾸면 **Principal ARN**과 **External ID**가 표시됩니다. 두 값을 복사해 둡니다.

    <Warning>
      Principal ARN은 **반드시 화면에 표시된 값**을 쓰세요. 환경에 따라 다르므로 문서의 예시를 옮겨 적으면 엉뚱한 주체를 신뢰하게 됩니다.
    </Warning>
  </Step>

  <Step title="역할 만들고 신뢰 정책 지정">
    **IAM → 역할 → 역할 생성**에서 **사용자 지정 신뢰 정책**을 선택하고 아래를 붙여넣습니다. 꺾쇠 두 곳을 앞 단계에서 복사한 값으로 바꾸세요.

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": { "AWS": "<화면에 표시된 Principal ARN>" },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": { "sts:ExternalId": "<화면에 표시된 External ID>" }
          }
        }
      ]
    }
    ```

    `sts:ExternalId` 조건은 **반드시** 넣어야 합니다. 이 조건이 없으면 역할 ARN을 알아낸 제3자가 OneSight를 거쳐 그 역할을 사용할 수 있습니다.
  </Step>

  <Step title="권한 연결하고 역할 ARN 복사">
    권한 단계에서 앞서 만든 `onesight-readonly` 정책을 연결하고 역할을 생성합니다. 생성된 역할의 **ARN**을 복사해 둡니다.
  </Step>
</Steps>

<Note>
  External ID는 **조직당 하나로 고정**된 값입니다. 데이터소스를 여러 개 등록하거나 다시 등록해도 바뀌지 않으므로, 신뢰 정책은 한 번만 설정하면 계속 유효합니다.
</Note>

### 액세스 키 방식

<Steps>
  <Step title="사용자 만들고 정책 연결">
    **IAM → 사용자 → 사용자 생성**으로 OneSight 전용 사용자를 만들고, 권한 설정 단계에서 **직접 정책 연결**을 선택해 앞서 만든 정책을 연결합니다.

    사람이 로그인할 계정이 아니므로 콘솔 로그인 권한은 주지 않아도 됩니다.
  </Step>

  <Step title="액세스 키 발급">
    생성한 사용자의 **보안 자격 증명** 탭에서 **액세스 키 만들기**를 선택하고, 사용 사례로 **AWS 외부에서 실행되는 애플리케이션**(서드 파티 서비스)을 고릅니다.

    발급된 **액세스 키**와 **시크릿 키**를 안전한 곳에 복사해 둡니다.
  </Step>
</Steps>

<Warning>
  시크릿 키는 발급 시 **한 번만** 표시됩니다. 이후에는 다시 확인할 수 없으므로 반드시 안전한 곳에 보관하세요. 분실하면 새 키를 발급받아야 합니다.
</Warning>

## 2단계: OneSight에 연결

<Steps>
  <Step title="스토리지 선택">
    **데이터소스 → 추가 → 스토리지 → Amazon S3**를 선택합니다.
  </Step>

  <Step title="접속 정보 입력 후 연결">
    1단계에서 선택한 **인증 방식**을 고르고 아래 항목을 입력한 뒤 연결을 확인합니다.

    | 항목            | 설명                              |
    | ------------- | ------------------------------- |
    | 역할 ARN        | *역할 위임 방식* — 1단계에서 만든 역할의 ARN   |
    | 액세스 키 / 시크릿 키 | *액세스 키 방식* — 1단계에서 발급한 키        |
    | 리전            | 버킷이 있는 리전 (예: `ap-northeast-2`) |
    | 버킷            | 연결할 버킷 이름                       |
    | 엔드포인트         | S3 호환 스토리지를 쓸 때만 입력합니다 (아래 참고)  |
    | 경로            | 특정 폴더만 탐색하려면 입력합니다 (선택)         |

    액세스 키 방식에서 입력한 시크릿 키는 등록 시 **AES-256-GCM 방식으로 암호화되어 저장**되며, 화면에 다시 표시되지 않습니다. 역할 위임 방식은 저장되는 장기 비밀이 없습니다.
  </Step>

  <Step title="파일 선택">
    폴더를 눌러 이동하고, 사용할 파일을 선택합니다. SQLite(`.db`) 파일이라면 이어서 조회할 **테이블**을 고릅니다.
  </Step>

  <Step title="확인 후 등록">
    미리보기로 데이터를 확인하고, 자동으로 제안된 매핑을 검토한 뒤 이름을 지정해 등록합니다.
  </Step>
</Steps>

## S3 호환 스토리지

MinIO, Cloudflare R2, Wasabi, NAVER·NHN·KT 클라우드 등 S3 호환 스토리지도 같은 방식으로 연결합니다. **엔드포인트**에 해당 스토리지의 주소를 입력하고, 필요하면 **path-style** 옵션을 켜세요. NAS에 MinIO를 올려 쓰는 경우도 여기에 해당합니다.

역할 위임은 AWS의 기능이므로 S3 호환 스토리지에서는 쓸 수 없습니다. **액세스 키** 방식으로 연결하세요.

<Warning>
  엔드포인트는 **외부에서 접속할 수 있는 주소**여야 합니다. 사내망이나 VPN 안에서만 열리는 주소는 보안 정책에 따라 차단됩니다.
</Warning>

## 지원 파일 형식과 크기

| 형식                      | 크기 제한                     |
| ----------------------- | ------------------------- |
| CSV                     | 제한 없음 — 파일 앞부분 4MB까지 읽습니다 |
| Excel (`.xlsx`, `.xls`) | 32MB                      |
| JSON                    | 32MB                      |
| SQLite (`.db`)          | 256MB                     |

Excel·JSON·SQLite는 형식 특성상 파일 전체를 받아야 열 수 있어 크기 제한이 있습니다. 제한을 넘으면 등록 단계에서 안내 메시지가 표시됩니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="SFTP 연결" icon="terminal" href="/data-sources/sftp">
    SFTP 서버의 파일을 연결합니다
  </Card>

  <Card title="문의하기" icon="message" href="/support/tickets">
    연결이 되지 않으면 문의해 주세요
  </Card>
</CardGroup>