> ## 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 버킷에 두면, OneS1ght가 조회 시점에 해당 파일을 직접 읽습니다. 파일을 복사해 보관하지 않으므로 원본을 교체하면 다음 조회부터 바로 반영됩니다.

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

## 준비물

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

## 인증 방식 두 가지

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

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

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

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

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

**1. 정책 만들기**

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

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

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

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

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

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

**1. OneS1ght 화면에서 값 두 개 확인**

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

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

**2. 역할 만들고 신뢰 정책 지정**

**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자가 OneS1ght를 거쳐 그 역할을 사용할 수 있습니다.

**3. 권한 연결하고 역할 ARN 복사**

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

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

### 액세스 키 방식

**1. 사용자 만들고 정책 연결**

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

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

**2. 액세스 키 발급**

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

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

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

## 2단계: OneS1ght에 연결

**1. 스토리지 선택**

**데이터소스 → 추가 → 스토리지 → Amazon S3**를 선택합니다.

**2. 접속 정보 입력 후 연결**

1단계에서 선택한 **인증 방식**을 고르고 아래 항목을 입력한 뒤 연결을 확인합니다.

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

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

**3. 파일 선택**

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

**4. 확인 후 등록**

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

## S3 호환 스토리지

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

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

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

## 지원 파일 형식과 크기

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

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

## 다음 단계

> **[SFTP 연결](/console/data-sources/sftp)**
>
> SFTP 서버의 파일을 연결합니다

> **[문의하기](/console/inquiries)**
>
> 연결이 되지 않으면 문의해 주세요


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.