S3 API 호환성

S3 API 호환성

MinIO(현 AIStor)는 분산 객체 스토리지의 표준인 Amazon S3 API를 그대로 지원해서, AWS S3용으로 만든 애플리케이션을 거의 코드 수정 없이 그대로 붙일 수 있어요. 이 페이지는 AIStor가 지원하는 S3 API가 정확히 무엇인지, 표준 S3와 어떤 점이 다른지 알려 드릴게요.

출처: S3 API Compatibility — MinIO AIStor Documentation

본문

조건부 헤더 (Conditional headers)

AIStor는 다음 HTTP 헤더를 이용한 조건부(conditional) 연산을 지원해요. 조건이 맞을 때만 연산을 수행하게 하려고 쓴답니다.

헤더 지원 연산
If-Match GetObject, HeadObject, PutObject, CopyObject, DeleteObject, CreateMultipartUpload
If-None-Match GetObject, HeadObject, PutObject, CopyObject, CreateMultipartUpload
If-Modified-Since GetObject, HeadObject
If-Unmodified-Since GetObject, HeadObject
x-amz-copy-source-if-match CopyObject, UploadPartCopy
x-amz-copy-source-if-none-match CopyObject, UploadPartCopy
x-amz-copy-source-if-modified-since CopyObject, UploadPartCopy
x-amz-copy-source-if-unmodified-since CopyObject, UploadPartCopy

DeleteObjects는 요청 본문의 <ETag> 요소를 이용해 조건부 삭제를 지원해요.

지원하지 않는 객체 API

다음 객체 API는 지원하지 않아요.

  • GetObjectAcl
  • PutObjectAcl

멀티파트 업로드

S3 API와의 차이점

  • ListMultipartUploads는 정확한 객체 이름을 프리픽스로 요구해요.
  • AbortIncompleteMultipartUpload 라이프사이클 액션은 PutBucketLifecycle과 함께 지원하지 않아요.

버킷 API

버킷 복제(replication), 버킷 라이프사이클, 버킷 알림(notification), 버킷 정책(policy)을 지원해요.

지원하지 않는 버킷 API 연산

  • GetBucketInventoryConfiguration
  • PutBucketInventoryConfiguration
  • DeleteBucketInventoryConfiguration
  • GetBucketMetricsConfiguration
  • PutBucketMetricsConfiguration
  • DeleteBucketMetricsConfiguration
  • PutBucketWebsite
  • GetBucketLogging
  • PutBucketLogging
  • PutBucketAccelerateConfiguration
  • DeleteBucketAccelerateConfiguration
  • PutBucketRequestPayment
  • DeleteBucketRequestPayment
  • PutBucketAcl
  • HeadBucketAcl
  • GetPublicAccessBlock
  • PutPublicAccessBlock
  • DeletePublicAccessBlock
  • GetBucketOwnershipControls
  • PutBucketOwnershipControls
  • DeleteBucketOwnershipControls
  • GetBucketIntelligentTieringConfiguration
  • PutBucketIntelligentTieringConfiguration
  • ListBucketIntelligentTieringConfigurations
  • DeleteBucketIntelligentTieringConfiguration
  • GetBucketAnalyticsConfiguration

지원하지 않는 버킷 API 연산의 대안

  • BucketACL 또는 ObjectACL 연산이 필요하면 Policies를 써요.
  • BucketWebsite 연산이 필요하면 caddy 또는 nginx를 써요.
  • BucketAnalytics, BucketMetrics, BucketLogging 연산이 필요하면 Bucket notifications를 써요.

S3 확장

AIStor는 표준 S3 API에 추가 기능을 덧붙여 제공해요.

S3 over RDMA

RDMA 빌드로 배포하면 GetObject, PutObject, UploadPart가 객체 데이터를 RDMA로 클라이언트 메모리와 서버 사이에 직접 전송해요. AWS S3 RDMA 프로토콜을 쓰는 방식이에요. GetObject는 클라이언트 버퍼에 쓰고, PutObject와 UploadPart는 그 버퍼에서 읽어요. 그 버퍼는 보통 GPU 메모리인데, RDMA가 가장 빛을 발하는 지점이죠. 호스트 메모리도 되고요.

클라이언트는 요청마다 헤더로 opt-in 해요. 서버 설정은 없어요.

헤더 방향 설명
x-amz-rdma-token 요청 클라이언트의 RDMA 버퍼 디스크립터
x-amz-rdma-reply 응답 전송이 RDMA로 이뤄졌으면 200 또는 206, 서버가 거절하면 501
x-amz-rdma-bytes-transferred 응답 대역외(outh of band)로 전송된 바이트 수 (0이 아닐 때)

RDMA 전송이 성공하면 서버는 Content-Length: 0으로 응답해요. 객체 바이트가 HTTP 응답으로 이동하지 않았기 때문이에요.

서버가 거절하면 HTTP로 객체를 서빙하는 대신 S3 오류 응답을 돌려줘요. x-amz-rdma-token 헤더 없이 재시도하는 것은 클라이언트 책임이에요. 아래 MinIO SDK는 이걸 자동으로 처리해요.

Reliable Connection 클라이언트는 먼저 POST /rdma/connect에서 핸드셰이크를 하고, 같은 x-amz-rdma-token 헤더로 디스크립터를 교환해요. Dynamically Connected 클라이언트는 이 라우트를 쓰지 않아요.

SDK 지원

S3 over RDMA는 Go, C++, Rust, Python용 MinIO SDK에서 지원돼요.

각 SDK는 NVIDIA cuObjClient를 사용해 객체 페이로드를 GPU 메모리와 네트워크 어댑터 사이에서 이동시켜요.

각 언어의 예제는 Transfer Objects over RDMA를, 배포 방법은 RDMA acceleration을 참고하세요.

S3 Express 모드

AIStor가 S3 Express 모드로 실행되면 지원하는 S3 API 표면이 기본 S3 API 모드와 달라져요. S3 Express 모드는 x-amz-write-offset-bytes 헤더를 가진 PutObject 요청으로 기존 객체에 데이터를 덧붙이는 AppendObject 동작도 추가해요. 지원·비활성화되는 연산 목록은 S3 Express mode를 참고하세요.

더 알아보기