본문으로 건너뛰기

주요 개념

객체

Object Storage에서 모든 파일은 객체의 형태(Key-Value 구조)로 저장되며, 버킷(Bucket)이라는 객체를 담을 수 있는 컨테이너에 포함됩니다. 파일은 객체의 하위 개념으로 객체의 형태 구조에서 Value에 해당하며, 파일을 인식할 수 있는 고유 식별자인 Key를 통해 접근할 수 있습니다.

객체의 키

객체의 키(Key)는 객체 고유의 식별자로, 버킷의 파일 위치로 표현됩니다. 예를 들어, 버킷의 kakao 폴더 하위에 위치한 i 폴더에 'cloud.png'라는 파일이 위치한다면, 객체의 키는 kakao/i/cloud.png와 같이 표현됩니다. 객체의 키는 디렉터리 계층 구조를 표현하는 /를 포함하여 432 bytes를 초과할 수 없습니다. 파일 업로드, 파일 이름 변경, 파일 이동 등 키(경로)가 변경되는 요청은 이와 같은 제약으로 실패할 수 있습니다.

안내

Object Storage에서 실제 데이터의 저장 및 조회는 폴더 기반 디렉터리 계층 구조가 아닌 평면 구조로 작동합니다. /로 구분하여 디렉터리 계층 구조를 나타낸 것은 사용자 편의 기능으로, 실제로는 계층과 관계없이 키에 대해 데이터가 맵핑되는 구조입니다.

객체 URL

버킷에 업로드된 파일(Value)에 접근하기 위해서는 객체 키 기반의 URL을 사용해야 합니다.
URL 구조는 https://objectstorage.{region-name}.kakaoi.io/v1/{project-ID}/{bucket-name}/{object-key}입니다. 파일별 URL 정보는 버킷 상세 페이지에서 확인할 수 있습니다. 자세한 설명은 객체 상세 화면을 참고하시기 바랍니다.

URL 구조
구분설명
region-name배포된 리전 이름
project-ID배포된 프로젝트의 ID
bucket-name생성한 버킷의 이름
object-key업로드한 객체의 키

콘솔 기반 파일 관리

콘솔(웹 브라우저)에서 버킷 내 파일을 관리할 수 있습니다. 자세한 설명은 객체 관리 문서를 참고하시기 바랍니다.

메타 데이터

객체를 설명하는 메타 데이터를 설정할 수 있습니다. 메타 데이터는 객체에 대한 정보를 Object Storage 시스템에 전달하는 목적의 시스템 메타 데이터와 사용자가 임의로 등록할 수 있는 사용자 메타 데이터로 구분됩니다. 자세한 설명은 파일 정보 확인을 참고하시기 바랍니다.

객체 태그

태그를 지정하여 객체를 분류할 수 있습니다. 객체 키(Key)와 키(Key)에 대한 값(Value)으로 구분되며 키(key)-값(value) 페어입니다. LifeCycle 규칙에 객체 태그를 이용하여 객체의 수명 주기를 관리할 수 있습니다. 자세한 설명은 객체 태그 설정을 참고하시기 바랍니다.

버킷

버킷은 객체를 담은 컨테이너로, 객체에 대한 접근 권한 및 라이프 사이클 설정의 적용 단위로 사용됩니다. 버킷 생성 및 관리에 대한 자세한 설명은 버킷 생성 및 관리를 참고하시기 바랍니다.

버킷 타입

Object Storage의 버킷은 Hot 버킷(kr-central-1)과 Standard 버킷(kr-central-2) 두 가지 타입을 제공하고 있으며, Cold 버킷(kr-central-1)을 지원할 예정입니다.
Hot 버킷은 읽기 요청이 많은 데이터를 저장하기에 적합하고 Standard 버킷은 높은 내구성과 가용성을 갖추어 자주 접근하는 데이터를 저장하기에 적합합니다. Cold 버킷은 잦은 접근이 불필요한 데이터를 합리적인 비용으로 저장하는 데 적합합니다.

라이프 사이클

버킷 라이프 사이클 정책에 따라 일정 시간이 지나면 버킷 내 파일을 자동 삭제하거나 다른 타입의 버킷으로 이동시킬 수 있습니다. 다른 타입으로 파일 이동 기능은 추후 업데이트 예정입니다. 라이프 사이클을 설정하는 방법은 Life Cycle 설정을 참고하시기 바랍니다.

버킷 공개 설정

버킷에 대해 퍼블릭 액세스를 설정하여 불특정 다수의 해당 버킷에 대한 외부 접근을 허용할 수 있습니다. 퍼블릭 액세스 설정 시, 공개된 버킷은 읽기 전용(Read Only)으로만 제공됩니다. 자세한 설명은 버킷 권한 관리를 참고하시기 바랍니다.

안내

파일 업로드 및 수정 등의 관리는 콘솔 또는 API를 통해서만 가능합니다.

안정성과 확장성

Object Storage에서는 버킷 용량과 객체 수에 제한이 없기 때문에, 데이터를 서로 다른 하드웨어에 분산하거나 중복으로 저장하여 안정성을 보장합니다. 또한 Object Storage는 계층화된 디렉터리 구조를 갖는 블록 스토리지(Block Storage)와 달리 Key-Value 형태의 평면 구조로 데이터를 저장해 확장이 용이합니다.
다른 설정을 하지 않아도 파일을 제한 없이 추가할 수 있으므로, 사용자는 스토리지 용량에 대한 고려 없이 서비스에 집중할 수 있습니다. 모든 데이터를 계층 구조 없이 평면에 저장하기에 계층 구조에 따른 속도 지연이 발생하지 않고, 버킷 내 파일 개수와 관계없이 빠른 접근을 보장합니다.

권한 관리

현재 일시적으로 IAM의 권한 체계와 Object Storage 권한 체계가 다르게 적용됩니다.
IAM 프로젝트 각 역할들은 아래와 같은 Object Storage 역할을 부여 받습니다.

IAM 역할Object Storage 역할
프로젝트 관리자스토리지 관리자(storage.admin)
프로젝트 멤버스토리지 편집자(storage.editor)
프로젝트 리더스토리지 뷰어(storage.viewer)

이미지. 권한 설정 아키텍처 권한 설정 아키텍처

권한
범위
역할(Role)권한(Permissions)S3 Bucket ACL
버킷스토리지 관리자
(storage.admin)
버킷과 객체를 관리할 수 있는 전체 권한을 부여
- storage.buckets.delete
- storage.buckets.get
- storage.buckets.update
- storage.buckets.getIamPolicy
- storage.buckets.setIamPolicy
- storage.objects.create
- storage.objects.delete
- storage.objects.list
- storage.objects.get
- storage.objects.update
FULL_CONTROL
스토리지 편집자
(storage.editor)
버킷의 권한 정책을 제외한 버킷과 객체를 관리할 수 있는 권한을 부여
- storage.buckets.get
- storage.buckets.update
- storage.objects.create
- storage.objects.delete
- storage.objects.list
- storage.objects.get
- storage.objects.update
READ + WRITE
스토리지 뷰어
(storage.Viewer)
버킷의 메타데이터 정보와 객체 메타 데이터를 볼 수 있는 권한을 부여
- storage.buckets.get
- storage.objects.list
- storage.objects.get
READ
스토리지 객체 관리자
(storage.objectAdmin)
객체 나열/생성/보기/삭제 등 전체 객체의 제어 권한을 부여
- storage.objects.create
- storage.objects.delete
- storage.objects.list
- storage.objects.get
- storage.objects.update
READ + WRITE
스토리지 객체 뷰어
(storage.objectReader)
버킷의 권한 정책을 제외한 객체 나열 및 메타 데이터를 볼 수 있는 권한을 부여
- storage.objects.list
- storage.objects.get
READ
스토리지 객체 생성자
(storage.objectCreator)
사용자에게 객체를 생성할 권한만 부여
- storage.objects.create
WRITE
스토리지 버킷 소유자
(storage.owner)
버킷의 생성을 제외한 버킷 조회 및 권한 정책을 관리할 수 있는 권한을 부여
- storage.buckets.delete
- storage.buckets.get
- storage.buckets.update
- storage.buckets.getIamPolicy
- storage.buckets.setIamPolicy
- storage.objects.create
- storage.objects.delete
- storage.objects.list
- storage.objects.get
- storage.objects.update
FULL_CONTROL
스토리지 버킷 편집자
(storage.policyEditor)
버킷의 생성/삭제를 제외한 버킷의 조회/권한 정책 및 객체를 관리할 수 있는 권한을 부여
- storage.buckets.get
- storage.buckets.update
- storage.buckets.getIamPolicy
- storage.buckets.setIamPolicy
- storage.objects.create
- storage.objects.delete
- storage.objects.list
- storage.objects.get
- storage.objects.update
FULL_CONTROL
스토리지 권한 정책 뷰어
(storage.policyReader)
버킷의 권한을 조회할 수 있는 권한을 부여
- storage.buckets.getIamPolicy
READ_ACP
스토리지 권한 정책 작성자
(storage.policyWriter)
버킷의 권한 조회를 제외한 추가/삭제할 수 있는 권한을 부여
- storage.buckets.setIamPolicy
WRITE_ACP

권한 유형

Object Storage의 권한 유형은 다음과 같습니다.

권한 유형설명
개인역할이 부여된 한 명의 사용자
그룹AllUserGroup의 유형 (모든 사용자)
서비스 계정서비스 계정은 사용자가 직접 생성하는 계정으로,
실제 IAM 사용자 계정은 아니며 카카오클라우드 API 호출에 필요한 인증 토큰을 발급할 수 있는 계정
역할 그룹IAM의 역할에 부여된 사용자 그룹
- 프로젝트 관리자(Admin): {project_id}
- 프로젝트 멤버(Member): {project_id}
- 프로젝트 리더(Reader) : {project_id}
- allUserGroup
주의

allUserGroup(kr-central-2에서 제공) 역할은 버킷에 접근하는 모든 사용자를 의미하기 때문에, 역할 부여에 주의가 필요합니다.

역할 초기 설정값

구성원에 대한 역할의 초기 설정값은 다음과 같습니다.

권한 범위구성원역할(Role)
버킷     프로젝트 관리자(Admin) : {project_id}스토리지 관리자
프로젝트 멤버(Member) : {project_id}스토리지 편집자
프로젝트 리더(Reader) : {project_id}스토리지 뷰어
버킷 생성자 : {user}스토리지 관리자

기능별 권한

버킷 또는 객체에 해당하는 권한 및 기능은 다음과 같습니다.

범위권한(Permission)기능
버킷storage.buckets.create버킷 생성하기
storage.buckets.delete버킷 삭제하기
storage.buckets.list버킷 목록 조회하기, 버킷의 메타 데이터 조회하기
storage.buckets.get버킷의 상세 정보, 메타 데이터 조회하기
storage.buckets.update버킷 수정하기
- 예시: 메타 데이터 수정
storage.buckets.getIamPolicy버킷 권한 정책 조회하기, Life Cycle 조회
storage.buckets.setIamPolicy버킷 권한 정책 등록, 수정, 삭제하기, Life Cycle 설정
객체storage.objects.create객체 등록하기
- 예시: 파일 업로드, 폴더 만들기
storage.objects.delete객체 삭제하기
storage.objects.list객체 조회하기
- 예시: 객체 목록 조회 및 객체의 메타 데이터 조회
storage.objects.get객체 상세 정보 조회하기
- 예시: 객체의 메타 데이터 조회, 객체 태그 조회, 파일 정보 조회, 파일 다운로드
storage.objects.update객체 수정하기
- 예시: 객체의 메타 데이터 추가/수정, 객체 태그 추가/삭제 , 이름 바꾸기
- storage.objects.create
- storage.objects.delete
- storage.objects.get
파일 이동하기
- storage.objects.create
- storage.objects.get
파일 복사하기

미디어 컨버트

안내

미디어 컨버터는 kr-central-1 리전에서 지원합니다.

미디어 컨버트는 버킷에 담긴 파일을 원하는 옵션에 따라 변환하고, 이미지 처리 기능을 제공하는 서비스입니다.
미디어 컨버트를 사용하면 효율적으로 트랜스 코딩할 수 있어 이미지 전송 링크 및 로딩 시 소모되는 시간을 효과적으로 단축하고, 대역폭 및 트래픽 비용을 절감할 수 있습니다. 이미지 처리, 영상 트랜스코딩 등 용도에 최적화된 변환 기능은 추후 지원 예정입니다.

또한 미디어 컨버트는 의도치 않은 파일에 대한 변환을 방지합니다. 클라우드 기반의 변환 서비스로 변환 정책 대상으로 설정한 버킷에 업로드된 파일을 제외한 나머지 의도치 않은 파일은 변환하지 않으며, 현재 Object Storage 버킷을 대상으로 설정한 정책을 따르는 미디어 콘텐츠 변환을 보장합니다.

정책 옵션

버킷의 객체에 대한 정책 옵션을 설정하여 사용자가 원하는 파일을 얻을 수 있습니다.

OperationTypeOption설명
resizesizescale지정한 사이즈만큼 크기가 조정된 후, 원하는 스케일만큼 크기를 변경
- 요청 형식에 따라 이미지의 너비나 높이의 비율이 유지되지 않을 수 있음
- 사이즈에 기입된 크기로 영상을 리사이즈한 후, 스케일을 적용함
cropsizescaleoffset스케일 적용 후 오프셋 위치(좌측 상단)부터 지정한 사이즈만큼 자름
- 스케일 후 오프셋 위치에서부터 사이즈만큼 크롭함
crop-centersize스케일을 다음 조건에 따라 적용 후, 사진의 중심을 기준으로 사이즈만큼 크롭함
- 너비 비율이 높을 경우 : 너비 비율에 따라 이미지 크기 조절
- 높이 비율이 높을 경우 : 높이 비율에 따라 이미지 크기 조절
crop-widthsize너비의 크기만큼 이미지를 스케일한 후, 높이의 사이즈만큼 높이를 크롭함

유형별 예시

리사이즈

리사이즈(resize)는 지정한 사이즈만큼 크기가 조정된 후, 원하는 스케일만큼 크기를 변경하는 것을 의미합니다. 요청 형식에 따라 이미지의 너비/높이 비율이 유지되지 않을 수 있습니다.

resize 예시
요청한 형식결과 크기결과설명
원본300x100       
size: 80x80
scale: 100
80x80비율이 유지되지 않음
size: 300x300
scale: 100
300x300비율이 유지되지 않음
size: 80x0
scale: 100
80x26비율 유지
size: 0x80
scale: 100
240x80비율 유지
size: 0x0
scale: 80
240x80비율 유지

크롭

크롭(crop)은 스케일 적용 후 오프셋 위치(좌측 상단)에서부터 지정한 사이즈만큼 자르는 것을 의미합니다.

crop 예시
요청한 형식결과 크기결과
원본300x100crop-예시-300x100
size: 249x135
offset: 0x0
249x100crop-예시-249x135
size: 249x135
offset: 100x50
200x50crop-예시-249x135_100x50
crop-center 예시
요청한 형식결과 크기결과 이미지
원본300x100
size: 80x8080x80
size: 400x80399x80
size: 80x40080x400
crop-width 예시
요청한 형식결과 크기결과 이미지
원본300x100
size: 100x10099x33
size: 500x100498x100