Azure S3 (Object Storage) Support Development

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 이상 (구독 범위)