> For the complete documentation index, see [llms.txt](https://ia-cloud.gitbook.io/cloudia-manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ia-cloud.gitbook.io/cloudia-manual/storage/object-storage.md).

# 오브젝트 스토리지

`오브젝트 스토리지`는 프로젝트에서 S3 호환 오브젝트 저장소를 생성하고 관리하는 화면입니다. 사용자는 오브젝트 스토리지를 생성한 뒤, 버킷을 추가하고 오브젝트를 저장할 수 있습니다. 인스턴스 내부에서 `object-storage.cloudia.internal` 도메인을 통해 접근합니다.

## 화면 개요

* `목록 화면`: 오브젝트 스토리지 현황을 조회하고 생성, 삭제 작업을 시작합니다.
* `상세 화면`: 기본 정보, 자격 증명 정보, 버킷 목록을 확인합니다.
* `생성 화면`: 이름과 포트 번호를 입력하여 새 오브젝트 스토리지를 생성합니다.

## 오브젝트 스토리지 목록

### 주요 작업

* `생성`: 새 오브젝트 스토리지를 추가합니다.
* `삭제`: 선택한 오브젝트 스토리지를 삭제합니다. 버킷이 없는 경우에만 삭제할 수 있습니다.

### 테이블 컬럼

| 컬럼        | 설명                        |
| --------- | ------------------------- |
| **이름**    | 오브젝트 스토리지의 이름을 나타냅니다.     |
| **ID**    | 오브젝트 스토리지의 고유 ID를 나타냅니다.  |
| **포트 번호** | 오브젝트 스토리지의 접속 포트를 나타냅니다.  |
| **생성일**   | 오브젝트 스토리지가 생성된 일시를 나타냅니다. |

***

## 오브젝트 스토리지 상세

오브젝트 스토리지 상세 화면에서는 선택한 오브젝트 스토리지의 상세 정보, 자격 증명 정보, 버킷 목록을 확인할 수 있습니다.

### 상세 정보

| 항목        | 설명                                             |
| --------- | ---------------------------------------------- |
| **이름**    | 오브젝트 스토리지의 이름을 나타냅니다.                          |
| **ID**    | 오브젝트 스토리지의 고유 ID를 나타냅니다.                       |
| **엔드포인트** | 오브젝트 스토리지 접속 주소를 나타냅니다. 인스턴스 내부에서 이 주소로 접근합니다. |
| **포트 번호** | 오브젝트 스토리지의 접속 포트를 나타냅니다.                       |
| **생성일**   | 오브젝트 스토리지가 생성된 일시를 나타냅니다.                      |

### 자격 증명 정보

| 항목        | 설명                         |
| --------- | -------------------------- |
| **액세스 키** | S3 호환 API 접근을 위한 액세스 키입니다. |
| **시크릿 키** | S3 호환 API 접근을 위한 시크릿 키입니다. |

> ⚠️ **주의:** 자격 증명 정보를 갱신하면 기존 키는 즉시 무효화됩니다. 기존 키를 사용하는 애플리케이션이 있다면 갱신 전 확인이 필요합니다.

### 버킷 섹션

상세 화면 하단에 버킷 목록이 표시됩니다.

| 컬럼        | 설명                                   |
| --------- | ------------------------------------ |
| **이름**    | 버킷의 이름을 나타냅니다.                       |
| **버킷 정보** | `보기` 버튼을 클릭하면 해당 버킷의 오브젝트 목록을 조회합니다. |

### 오브젝트 섹션

버킷의 `보기` 버튼을 클릭하면 하단에 해당 버킷의 오브젝트 목록이 표시됩니다.

| 컬럼          | 설명                     |
| ----------- | ---------------------- |
| **오브젝트 이름** | 오브젝트의 키(경로 포함)를 나타냅니다. |

***

## 오브젝트 스토리지 생성

오브젝트 스토리지 생성 화면에서는 이름과 포트 번호를 입력하여 새 오브젝트 스토리지를 생성합니다.

> ⚠️ **참고:** 오브젝트 스토리지 생성은 비동기로 처리됩니다. 생성 요청 후 목록에 나타나기까지 약 20\~30초가 소요될 수 있습니다.

### 기본 정보

* **이름**: 오브젝트 스토리지의 이름을 입력합니다.
* **포트 번호**: 오브젝트 스토리지의 접속 포트를 입력합니다.

### 입력 필드 유효성

| 필드        | 허용 값                      | 검증 규칙                        | 비고                          |
| --------- | ------------------------- | ---------------------------- | --------------------------- |
| **이름**    | 영문 대/소문자, 숫자, `-` 조합의 문자열 | 필수입니다. 3\~25자 이내로 입력합니다.     | 오브젝트 스토리지 식별용 이름입니다.        |
| **포트 번호** | 20000\~49999 범위의 정수       | 필수입니다. 지정 범위 내 유효한 정수여야 합니다. | 다른 오브젝트 스토리지와 중복되지 않아야 합니다. |

***

## 오브젝트 스토리지 삭제

* 삭제는 한 번에 1개만 수행합니다.
* 버킷이 남아 있으면 삭제할 수 없습니다. 삭제 전에 모든 버킷을 먼저 제거해야 합니다.
* 삭제 확인 모달에서 대상의 이름, ID, 포트 번호, 생성일 정보를 확인할 수 있습니다.

***

## 버킷 관리

버킷은 오브젝트 스토리지 상세 화면에서 생성 및 삭제합니다.

### 버킷 생성

1. 상세 화면의 버킷 섹션에서 **생성**을 클릭합니다.
2. 모달에서 버킷 **이름**을 입력합니다.
3. **생성**을 클릭하여 버킷을 추가합니다.

### 버킷 삭제

1. 버킷 목록에서 삭제할 버킷을 선택합니다.
2. **삭제**를 클릭합니다.
3. 확인 모달에서 **삭제**를 클릭합니다.

> ⚠️ **주의:** 버킷 내에 오브젝트가 남아 있으면 삭제할 수 없습니다 (`Bucket is not empty`). 버킷 삭제 전에 모든 오브젝트를 먼저 제거해야 합니다.

***

## 자격 증명 갱신

상세 화면에서 **자격 증명 정보 갱신** 버튼을 클릭하면 액세스 키와 시크릿 키를 새로 발급합니다.

1. 상세 화면에서 **자격 증명 정보 갱신**을 클릭합니다.
2. 확인 모달에서 **확인**을 클릭합니다.
3. 새로운 액세스 키와 시크릿 키가 발급됩니다.

> ⚠️ **주의:** 갱신 후 기존 키는 즉시 무효화됩니다. 인스턴스 내부에서 기존 키를 사용 중인 경우 새 키로 교체해야 합니다.

***

## 인스턴스에서 오브젝트 스토리지 접근

오브젝트 스토리지를 사용하려면 인스턴스 생성 시 **오브젝트 스토리지 활성화** 옵션을 켜야 합니다. 활성화하면 Managed VNIC가 자동 추가되고, 인스턴스 내부에서 `object-storage.cloudia.internal` 도메인으로 접근할 수 있습니다.

### 접근 예시 (s5cmd)

```bash
# s5cmd 설치
curl -sL https://github.com/peak/s5cmd/releases/download/v2.3.0/s5cmd_2.3.0_Linux-64bit.tar.gz -o /tmp/s5cmd.tar.gz && sudo tar xzf /tmp/s5cmd.tar.gz -C /usr/local/bin s5cmd

# 버킷 목록 조회
AWS_ACCESS_KEY_ID={액세스키} AWS_SECRET_ACCESS_KEY={시크릿키} AWS_REGION=cloudia \
  s5cmd --endpoint-url http://object-storage.cloudia.internal:{포트번호} ls

# 오브젝트 업로드
AWS_ACCESS_KEY_ID={액세스키} AWS_SECRET_ACCESS_KEY={시크릿키} AWS_REGION=cloudia \
  s5cmd --endpoint-url http://object-storage.cloudia.internal:{포트번호} cp ./myfile.txt s3://my-bucket/myfile.txt
```

> ⚠️ **참고:** 호스트 머신에서 직접 접근할 때는 `object-storage.cloudia.internal` 대신 스토리지 네트워크 VIP(예: `30.0.0.10`)를 endpoint로 사용해야 합니다. 이 DNS는 인스턴스 내부의 Managed VNIC 네트워크에서만 해석됩니다.