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

# Storage Connection

> 프로젝트 레벨 Storage Connection 설정으로 암호화된 액세스 키와 허용 대상 스코프를 지정해 Starfort가 S3 버킷에 접근하도록 합니다 (Starfort v1.4 문서)

Starfort가 원본을 읽고 산출물을 기록하려면 스토리지 접근 수단이 필요합니다. 이 접근 수단은 **Storage Connection**으로 **Project 단위로 사전 등록**하며, 등록이 없으면 배치 접수 자체가 거부됩니다(`S3_CONNECTION_NOT_CONFIGURED` — [배치 오류](/ko/v1.4/api/batch/errors) 참고).

등록·관리는 관리 콘솔의 설정 영역에서 수행하며, 등록 · 변경 · 삭제는 모두 [감사 로그](/ko/v1.4/admin/audit-log)에 기록됩니다.

## 등록 내용

| 항목        | 내용                                               |
| --------- | ------------------------------------------------ |
| **접속 정보** | S3 호환 endpoint URL과 접근 자격증명(access key / secret) |
| **허용 대상** | 읽기 가능한 버킷 · 경로(prefix)와 쓰기 가능한 버킷 · 경로의 명시적 목록   |

접근 자격증명에는 **최소 권한**만 부여하세요 — 원본 경로에 읽기(`GetObject`), 결과 경로에 쓰기(`PutObject`)면 충분합니다.

## 접근 키 암호화 보관

접근 키의 비밀 값은 **암호화되어 보관**되며, 등록 후 어떤 조회에도 다시 노출되지 않습니다.

## 허용 대상 스코프

작업의 두 주소는 각각 등록된 허용 대상과 대조됩니다:

* `src_s3_url`은 **읽기** 허용 범위 안이어야 합니다.
* `tgt_s3_url`은 **쓰기** 허용 범위 안이어야 합니다.

어느 한쪽이라도 등록 범위 밖이면 접수가 거부되고 작업이 만들어지지 않습니다(`S3_TARGET_NOT_ALLOWED`). 등록 시점에 위임 범위를 최소로 좁히는 구조이므로, 자격증명이 실수로 다른 경로에 쓰이는 일을 방지합니다.

## 스토리지 유형

Storage Connection은 **유형**을 가지며, 유형에 따라 등록 내용이 갈립니다. Project 단위 등록, 허용 범위 강제, 감사 로그 대상이라는 골격은 두 유형이 공유합니다.

| 항목           | 오브젝트 스토리지 유형                 | 파일 스토리지 유형                    |
| ------------ | ---------------------------- | ----------------------------- |
| **접속 정보**    | 접속 주소 · 접근 키(암호화 보관, 재노출 없음) | 없음 — 플랫폼에 사전 연결된 영역을 가리키는 식별자 |
| **허용 대상**    | 버킷 · 경로 접두어 · 읽기/쓰기 구분       | 경로 접두어 · 읽기/쓰기 구분             |
| **허용 범위 강제** | 등록 범위 밖 주소는 접수 거부            | 동일                            |
| **시크릿 보호**   | 대상                           | 해당 없음 — 보관할 비밀 값이 없음          |
| **연결 준비**    | 등록만으로 성립                     | 등록에 앞서 플랫폼에 해당 영역이 연결되어 있어야 함 |
| **제공 조건**    | 배포 형태 무관                     | **고객 전용 배포에서만 제공**            |

한 작업의 원본과 결과는 **서로 다른 Storage Connection으로 해석**됩니다 — 원본 주소는 읽기 허용 범위를 가진 설정에서, 결과 저장 주소는 쓰기 허용 범위를 가진 설정에서 각각 대조되며, 두 설정의 유형이 달라도 무방합니다(예: 원본은 오브젝트 스토리지, 결과는 파일 스토리지).

### 파일 스토리지 유형에서 달라지는 것

파일 스토리지는 요청 단위 자격증명이 아니라 **플랫폼에 사전 연결된 영역**으로 접근하므로, 다음이 달라집니다:

* **연결이 사전 준비입니다.** 고객 환경과 플랫폼 사이의 연결이 갖춰진 뒤에야 연계 설정 등록이 의미를 가지며, 연결이 없는 상태의 등록은 접수 거부로 이어집니다.
* **연계 영역 접근 불가는 원본 부재와 구분됩니다.** 연결이 끊긴 상태는 "비어 있는 경로"처럼 보일 수 있으므로, 실행 계층은 원본을 읽기 전과 결과를 쓰기 전에 연계 영역의 연결 여부를 먼저 확정하고, 연결되어 있지 않으면 원본 부재와 구분되는 별도 사유로 작업을 실패 처리합니다.
* **결과 저장은 연결이 확인된 영역에만 이뤄집니다.** 연결이 확인되지 않은 상태의 저장 시도는 기록 실패로 확정됩니다 — 산출물 없는 완료는 만들지 않습니다.
* **산출물의 접근 권한은 사전 합의된 값으로 고정됩니다.** 결과 파일이 후속 처리 주체에게 읽힐 수 있어야 연계가 성립하기 때문입니다.

판정별 산출물 규칙과 검사 한도는 스토리지 유형과 무관하게 동일합니다. [산출물 규칙과 한도](/ko/v1.4/api/batch/outputs-and-limits)를 참고하세요.