Azure S3 (Object Storage) Support Development - cloud-barista/cb-spider GitHub Wiki

Azure S3 (Object Storage) Support Development

1. 개요

CB-Spider의 S3 Manager에 Azure Blob Storage 지원을 추가하였다.
기존 AWS, GCP, IBM 등은 S3 호환 API(minio-go)를 사용하지만, Azure는 S3 호환 API를 제공하지 않으므로 Azure Go SDK(azblob)를 이용한 Native 구현 방식을 채택하였다.

설계 원칙

GCP Native SDK 처리 패턴(Versioning/CORS/Force 분기)을 확장하여 전 기능 Azure Native 분기
기존 minio-go 기반 코드를 변경하지 않고, connInfo.ProviderName == "AZURE" 분기로 Azure 전용 함수 호출
Azure 전용 로직은 별도 파일(S3Manager_azure.go)에 분리
CB-Spider가 제공하는 3가지 API 규격(CB Standard JSON, AWS-compatible XML with Basic Auth, AWS-compatible XML with SigV4) 모두 동일하게 지원

2. Azure ↔ S3 개념 매핑

S3 개념	Azure 구현	비고
Bucket	Container	이름 규칙: 소문자, 3-63자, 하이픈 허용
Object	Blob	Block Blob 기반
Multipart Upload	Block Blob (StageBlock/CommitBlockList)	Upload ID는 xid로 자체 생성
Presigned URL	SAS (Shared Access Signature) Token URL	`sas.BlobSignatureValues` 기반
Versioning	Storage Account 레벨 (ARM API)	개별 Bucket 단위 설정 불가
CORS	Storage Account 레벨 (Service Properties)	개별 Bucket 단위 설정 불가
Delete Marker	미지원	Azure는 Soft Delete 사용
AccessKey / SecretKey	StorageAccountName / StorageAccountKey

3. 인증 정보 매핑

Data Plane (Blob 조작)

S3ConnectionInfo 필드	Azure Credential 소스	값 예시
`AccessKey`	`S3AccessKey` 또는 `StorageAccountName`	`mystorageaccount`
`SecretKey`	`S3SecretKey` 또는 `StorageAccountKey`	`base64encodedkey==`
`Endpoint`	자동 생성	`mystorageaccount.blob.core.windows.net`
`UseSSL`	항상 `true`	HTTPS 강제
`Region`	Connection Config에서 전달	필수 아님

Management Plane (Versioning 등 ARM API)

ARM 작업(Versioning Enable/Suspend/Get)에는 Service Principal 인증이 필요하며, 동일 Connection Config의 Credential에서 가져온다:

필드	Credential Key
`SubscriptionId`	`SubscriptionId`
`TenantId`	`TenantId`
`ClientId`	`ClientId`
`ClientSecret`	`ClientSecret`
`StorageAccountName`	`S3AccessKey` 또는 `StorageAccountName`

4. 변경 파일 목록

파일	변경 유형	설명
`api-runtime/common-runtime/S3Manager_azure.go`	신규	Azure 전용 S3 기능 구현 (37개 함수, ~1,350줄)
`api-runtime/common-runtime/S3Manager.go`	수정	32개 함수에 `AZURE` 분기 추가 + `GetS3ConnectionInfo`에 AZURE case 추가
`go.mod`	수정	`github.com/Azure/azure-sdk-for-go/sdk/storage/azblob v1.5.0` 의존성 추가
`go.sum`	수정	자동 갱신

5. 구현 함수 목록 (S3Manager_azure.go)

Client Helper

함수	설명
`newAzureBlobClient`	SharedKeyCredential 기반 Azure Blob 클라이언트 생성
`getAzureManagementInfo`	Connection Config에서 ARM용 SP 인증 정보 추출
`getAzureResourceGroup`	Storage Account가 속한 Resource Group 자동 탐색
`azureBlockID`	Multipart용 Base64 Block ID 생성 (uploadID prefix + part number)
`stripAzureETagQuotes`	Azure ETag에서 따옴표 제거

Bucket (Container) 작업

함수	설명
`createAzureBucket`	Container 생성
`listAzureBuckets`	Container 목록 조회 → `[]*minio.BucketInfo`
`listAzureBucketsWithIID`	Container 목록 + IID 정보 조회
`getAzureBucket`	단일 Container 정보 조회
`deleteAzureBucket`	Container 삭제

Object (Blob) 작업

함수	설명
`listAzureObjects`	Container 내 Blob 목록 조회 (prefix 필터)
`azureBlobItemToObjectInfo`	Azure BlobItem → minio.ObjectInfo 변환
`getAzureObjectInfo`	Blob 속성 조회 (크기, ETag, ContentType, VersionID)
`getAzureObjectInfoWithVersion`	특정 버전 Blob 속성 조회
`deleteAzureObject`	Blob 삭제
`deleteAzureObjectVersion`	특정 버전 Blob 삭제
`deleteMultipleAzureObjects`	다수 Blob 순차 삭제
`deleteMultipleAzureObjectVersions`	다수 버전 Blob 순차 삭제

Stream 작업

함수	설명
`getAzureObjectStream`	Blob 다운로드 → `io.ReadCloser`
`getAzureObjectStreamWithVersion`	특정 버전 Blob 다운로드
`putAzureObject`	Blob 업로드 (`UploadStream`)
`getAzureBucketTotalSize`	Container 전체 크기 계산

Multipart (Block Blob) 작업

함수	설명
`initiateAzureMultipartUpload`	Upload ID 생성 (xid 기반, Azure는 명시적 initiation 불필요)
`uploadAzurePart`	Block 스테이징 (`StageBlock`)
`completeAzureMultipartUpload`	Block List 커밋 (`CommitBlockList`)
`abortAzureMultipartUpload`	No-op (Azure는 7일 후 자동 정리)
`listAzureParts`	Uncommitted Block 목록 조회 (`GetBlockList`)

Versioning (ARM Management Plane)

함수	설명
`enableAzureVersioning`	Storage Account 레벨 Versioning 활성화
`suspendAzureVersioning`	Storage Account 레벨 Versioning 비활성화
`getAzureVersioning`	Versioning 상태 조회
`listAzureObjectVersions`	Container 내 Blob 버전 목록 조회

CORS (Service Properties)

함수	설명
`setAzureBucketCORS`	CORS 규칙 설정 (Storage Account 레벨)
`getAzureBucketCORS`	CORS 규칙 조회 → `*cors.Config`
`deleteAzureBucketCORS`	CORS 규칙 삭제 (빈 규칙 설정)

Presigned URL (SAS)

함수	설명
`getAzurePresignedURL`	GET(Read) 또는 PUT(Write/Create) SAS URL 생성

Force 작업

함수	설명
`forceEmptyAzureBucket`	모든 Blob(버전 포함) 강제 삭제
`forceEmptyAndDeleteAzureBucket`	강제 비우기 + Container 삭제 + DB 메타데이터 정리

6. 사용된 Azure SDK 모듈

모듈	버전	용도
`azure-sdk-for-go/sdk/storage/azblob`	v1.5.0	Blob Storage 데이터 플레인 (신규 추가)
`azure-sdk-for-go/sdk/resourcemanager/storage/armstorage`	v1.8.0	Storage Account ARM 관리 (기존)
`azure-sdk-for-go/sdk/azcore`	v1.18.0	Core SDK, `to.Ptr()`, `streaming.NopCloser` (기존)
`azure-sdk-for-go/sdk/azidentity`	v1.10.1	Service Principal 인증 (기존)

7. CSP별 S3 기능 지원 현황 비교표

기능	AWS	GCP	Azure	IBM	Alibaba	Tencent	OpenStack	NHN	NCP	KT
Bucket CRUD	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Object CRUD	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Object Stream	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Multipart Upload	✅	✅	❌	✅	✅	✅	❌	✅	✅	✅
ListMultipartUploads	✅	✅	❌	✅	✅	✅	❌	✅	✅	✅
Presigned URL	✅	✅	✅(SAS)	✅	✅	✅	✅	✅	✅	✅
Versioning	✅	✅	❌	✅	✅	✅	❌	❌	❌	✅
CORS	✅	✅	❌	✅	✅	✅	✅	❌	❌	✅
Delete Marker	✅	✅	❌	✅	✅	✅	❌	❌	❌	✅
Delete Multiple	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Force Empty	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Force Empty+Delete	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

❌ = 미지원 (해당 CSP 구조적 제약)

8. Azure에서 제공할 수 없는 기능 (비지원 사항)

8.1 Delete Markers (`DeleteS3ObjectDeleteMarker`)

사유: Azure Blob Storage는 S3 스타일 Delete Marker를 사용하지 않는다.
Azure 방식: Soft Delete를 사용하며, 삭제된 blob은 설정된 보존 기간(retention period) 이후 자동 제거된다.
처리: "delete markers are not supported by Azure Blob Storage" 에러 반환 (HTTP 501)

8.2 Multipart Upload (전체)

사유: Azure Block Blob은 uncommitted blocks를 7일 후 자동 정리하며, 진행 중인 multipart upload 목록을 조회하는 API(ListMultipartUploads)가 없다. 목록 조회가 불가능하면 업로드 상태 관리가 불완전하므로 Multipart Upload 전체를 미지원으로 처리한다.
영향 함수: InitiateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload, ListParts, ListMultipartUploads
처리: "multipart upload is not supported by ..." 에러 반환 (HTTP 501)
대안: 단일 업로드(PUT /bucket/object)를 사용한다.

8.3 Versioning (`EnableVersioning`, `SuspendVersioning`, `GetVersioning`, `ListObjectVersions`, `DeleteObjectVersion`)

사유: Azure Blob Storage의 Versioning은 Storage Account 전체에 적용되며, 개별 Container(Bucket) 단위로 제어할 수 없다. S3 API는 Bucket 단위 Versioning을 전제로 하므로 호환되지 않는다.
처리: "bucket versioning is not supported by ..." 에러 반환 (HTTP 501)

8.4 CORS (`SetBucketCORS`, `GetBucketCORS`, `DeleteBucketCORS`)

사유: Azure의 CORS 설정은 Storage Account 전체에 적용되며, 개별 Container(Bucket) 단위로 격리할 수 없다. S3 API는 Bucket 단위 CORS를 전제로 하므로 호환되지 않는다.
처리: "CORS configuration is not supported by ..." 에러 반환 (HTTP 501)

9. Presigned URL (SAS Token) 구현

Azure의 SAS(Shared Access Signature)를 이용하여 S3 Presigned URL과 동일한 기능을 제공한다:

HTTP Method	SAS Permission	설명
`GET`	`Read`	Blob 다운로드
`PUT`	`Write + Create`	Blob 업로드

생성된 URL 형식:

https://{storageAccount}.blob.core.windows.net/{container}/{blob}?{sasToken}

11. 사전 요구사항

Azure Credential 설정

CB-Spider에서 Azure S3를 사용하려면 다음 Credential이 필요하다:

{
  "CredentialName": "azure-s3-credential",
  "ProviderName": "AZURE",
  "KeyValueInfoList": [
    {"Key": "SubscriptionId", "Value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
    {"Key": "TenantId", "Value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
    {"Key": "ClientId", "Value": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
    {"Key": "ClientSecret", "Value": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
    {"Key": "StorageAccountName", "Value": "mystorageaccount"},
    {"Key": "StorageAccountKey", "Value": "base64encodedkey=="}
  ]
}

StorageAccountName/StorageAccountKey 대신 S3AccessKey/S3SecretKey 키 이름도 사용 가능

필요 Azure 권한

작업 유형	필요 권한
Blob 데이터 조작 (CRUD, Stream, Multipart)	Storage Account Key (SharedKey 인증)
Versioning Enable/Suspend/Get	Service Principal + `Storage Account Contributor` 이상
Resource Group 탐색	Service Principal + `Reader` 이상 (구독 범위)