S3 API로 Object Storage 사용

S3 호환 API를 통해 카카오클라우드 Object Storage를 CLI 및 SDK에서 사용하는 방법을 안내합니다.

기본 정보

예상 소요 시간: 30분
권장 운영 체제: MacOS, Ubuntu
사전 준비 사항
- S3 액세스 키 발급

시나리오 소개

카카오클라우드 Object Storage는 AWS S3와 호환되는 일부 API를 제공하므로, 기존에 S3를 사용하던 환경에서도 그대로 연동해 사용할 수 있습니다. 이 튜토리얼에서는 콘솔에서 발급받은 S3 액세스 키를 이용해 AWS CLI, Python Boto3, Java, Go SDK를 통해 버킷과 객체를 관리하는 방법을 설명합니다.

주요 내용은 다음과 같습니다.

콘솔에서 S3 액세스 키 발급
AWS CLI를 이용한 버킷 및 객체 관리
Boto3, Java SDK, Go SDK를 이용한 S3 API 호출 예제 코드

기존 AWS S3에 맞춰 개발된 도구나 애플리케이션이 있다면, 설정을 변경하여 카카오클라우드 Object Storage로 손쉽게 이전할 수 있습니다. AWS S3에서 카카오클라우드 Object Storage로 데이터 이관 튜토리얼을 참고하세요.

시작하기 전에

S3 액세스 키 발급

카카오클라우드 콘솔에서 직접 S3 액세스 키를 발급할 수 있습니다.

카카오클라우드 콘솔에 접속한 후, 화면 우측 상단의 프로필 아이콘 > 자격 증명 메뉴를 선택합니다.
비밀번호를 다시 입력하고 비밀번호 확인을 진행합니다.
S3 액세스 키 탭으로 이동하여 [S3 액세스 키 생성] 버튼을 클릭합니다.
팝업창에서 필요한 정보를 입력 후 [생성] 버튼을 누르면, 액세스 키와 보안 액세스 키가 발급됩니다.
안내
- 프로젝트 당 최대 2개의 S3 액세스 키를 생성할 수 있습니다.
- 사용자가 프로젝트에서 삭제될 경우, 발급된 키는 자동으로 만료됩니다.
생성된 키 정보를 안전한 위치에 저장하고, 이후 CLI 및 SDK 설정 시 사용합니다.

Type 1. AWS CLI 예제

AWS 명령줄 인터페이스(CLI)를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

AWS CLI 설정

AWS CLI 실행을 위한 자격 증명과 환경을 설정합니다. 만약 AWS CLI가 설치되어 있지 않다면, 먼저 AWS CLI를 설치합니다.

Mac
Linux(Ubuntu)

curl 명령어를 이용하여 AWS CLI를 설치합니다.

안내
카카오클라우드에서 호환 가능한 S3 CLI의 최신 버전은 2.22.0입니다. 2.22.0 보다 상위 버전을 사용할 경우, S3 명령 요청의 정상 작동이 보장되지 않을 수 있습니다.
curl 명령어 이용
```
curl "https://awscli.amazonaws.com/AWSCLIV2-2.22.0.pkg" -o "AWSCLIV2-2.22.0.pkg"
sudo installer -pkg AWSCLIV2-2.22.0.pkg -target /
```
설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.
경로 확인
```
which aws
/usr/local/bin/aws
```
버전 확인
```
aws --version
aws-cli/2.10.0 Python/3.11.2 Darwin/18.7.0 botocore/2.4.5
```

curl 명령어를 이용하여 설치합니다.

curl 명령어 이용
$ curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
$ sudo installer -pkg AWSCLIV2.pkg -target /

설치가 정상적으로 되었는지 아래 명령어를 통해 확인합니다.

AWS CLI 설치 확인
# 경로 확인
$ which aws
/usr/local/bin/aws

# 버전 확인
$ aws --version
aws-cli/2.10.0 Python/3.11.2 Darwin/18.7.0 botocore/2.4.5

이어서 진행하기 위해 S3 사용에 필요한 크리덴셜 값을 확인합니다.

configure 명령을 이용하여 설정을 진행합니다.
```
aws configure
```

다음을 참고하여 사용자의 자격 증명을 입력합니다.

AWS Access Key ID: {S3_ACCESS_KEY}
AWS Secret Access Key: {S3_SECRET_ACCESS_KEY}
Default region name: kr-central-2
Default output format:

설정이 끝나면 다음과 같은 방법으로 s3 명령을 사용할 수 있습니다.
```
aws --endpoint-url={endpoint} s3 {command} s3://{bucket}
```
```
# Example
# aws --endpoint-url=https://objectstorage.kr-central-2.kakaocloud.com s3 ls
```
리전 엔드포인트
kr-central-2 https://objectstorage.kr-central-2.kakaocloud.com

리전	엔드포인트
kr-central-2	`https://objectstorage.kr-central-2.kakaocloud.com`

AWS CLI 사용 예시

버킷 생성
aws --endpoint-url={endpoint} s3 mb s3://{bucket_name}

전체 버킷 목록 조회
aws --endpoint-url={endpoint} s3 ls

특정 버킷 내부 조회
aws --endpoint-url={endpoint} s3 ls s3://{bucket_name}

버킷 삭제
aws --endpoint-url={endpoint} s3 rb s3://{bucket_name}

파일 업로드
aws --endpoint-url={endpoint} s3 cp {local_path} s3://{bucket_name}/{upload_path}

파일 다운로드
aws --endpoint-url={endpoint} s3 cp s3://{bucket_name}/{file_path} {local_path}

파일 삭제
aws --endpoint-url={endpoint} s3 rm s3://{bucket_name}/{file_path}

Type 2. Python SDK(Boto3) 예제

AWS Python SDK(Boto3)를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

S3 클라이언트 생성 및 설정

pip를 이용하여 boto3을 설치합니다.
```
$ pip install boto3
```
안내
현재 boto3은 Python 3.8 이상 버전에서만 지원됩니다.

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

import boto3

client = boto3.client(
    region_name="kr-central-2",
    endpoint_url="{ENDPOINT}",
    aws_access_key_id="{S3_ACCESS_KEY}",
    aws_secret_access_key="{S3_SECRET_ACCESS_KEY}",
    service_name="s3"
)

SDK 사용 예시

버킷 생성
def create_bucket(bucket_name):
    try:
        return client.create_bucket(Bucket=bucket_name)
    except Exception as e:
        raise #...

전체 버킷 목록 조회
def get_list_buckets() :
    try:
        response = client.list_buckets()
        return [bucket.get('Name') for bucket in response.get('Buckets', [])]
    except Exception as e:
        raise #...

특정 버킷 내부 조회
def get_list_objects(bucket_name):
    try:
        response = client.list_objects(Bucket=bucket_name)
        return [obj.get('Key') for obj in response.get('Contents', [])]
    except Exception as e:
        raise #...

버킷 삭제
def delete_bucket(bucket_name):
    try:
        return client.delete_bucket(Bucket=bucket_name)
    except Exception as e:
        raise #...

파일 업로드
# local_path : 업로드할 파일이 위치한 로컬 경로
# file_name : 업로드할 파일명
def upload_file(local_path, bucket_name, file_name) :
    try :
        # client.upload_file('/Documents/hello.jpeg', 'bucket', 'hello.jpeg')
        return client.upload_file(local_path, bucket_name, file_name)
    except Exception as e:
        raise

파일 다운로드
# file_name : 다운로드할 파일명
# local_path : 파일을 내려받을 로컬 경로 및 파일명
def download_file(bucket_name, file_name, local_path) :
    try :
        # client.download_file('bucket', 'hello.jpeg', '/Downloads/hello.jpeg')
        return client.download_file(bucket_name, file_name, local_path)
    except Exception as e:
        raise

파일 삭제
def delete_object(bucket_name, file_name) :
    try :
        return client.delete_object(Bucket=bucket_name, Key=file_name)
    except Exception as e :
        raise

Type 3. Java SDK 예제

AWS Java SDK를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다. 해당 문서는 aws-java-sdk-v2를 기준으로 작성되었습니다.

S3 클라이언트 생성 및 설정

Maven
Gradle

pom.xml에 다음과 같이 의존성을 추가합니다.

<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.23.7</version>
    </dependency>

    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>1.7.32</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.4.12</version>
    </dependency>
</dependencies>

추가한 의존성을 반영하기 위해 Maven을 새로 빌드합니다.

build.gradle에 다음과 같이 의존성을 추가합니다.

implementation platform('software.amazon.awssdk:bom:2.23.7')
implementation 'software.amazon.awssdk:s3'
implementation 'ch.qos.logback:logback-classic:1.4.12'

추가한 의존성을 반영하기 위해 Gradle을 새로 빌드합니다.

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

String s3Endpoint = "https://objectstorage.kr-central-2.kakaocloud.com";
String accessKey = "{S3_ACCESS_KEY}";
String secretAccessKey = "{S3_SECRET_ACCESS_KEY}";
String region = "kr-central-2";


final S3Client client = S3Client.builder()
    .credentialsProvider(StaticCredentialsProvider.create(AwsBasicCredentials.create(accessKey, secretAccessKey)))
    .endpointOverride(URI.create(s3Endpoint))
    .forcePathStyle(true)
    .region(Region.of(region))
    .build();

SDK 사용 예시

버킷 생성
private void createBucket(S3Client client, String bucketName) {
    try {
        CreateBucketResponse res = client.createBucket(
            CreateBucketRequest.builder()
                .bucket(bucketName)
                .build());
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

전체 버킷 목록 조회
private void listBuckets(S3Client client) {
    try {
        ListBucketsResponse res = client.listBuckets();
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

특정 버킷 내부 조회
private void listObjects(S3Client client, String bucketName) {
    try {
        ListObjectsResponse res = client.listObjects(
            ListObjectsRequest.builder()
                .bucket(bucketName)
                .build());
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

버킷 삭제
private void deleteBucket(S3Client client, String bucketName) {
    try {
        DeleteBucketResponse res = client.deleteBucket(
            DeleteBucketRequest.builder()
                .bucket(bucketName)
                .build());
        System.out.println(res);
    }
    catch (Exception e){
        e.printStackTrace();
    }
}

파일 업로드
// objectKey : 업로드할 파일명
// filePath : 업로드할 파일이 위치한 로컬 경로
private void uploadObject(S3Client client, String bucketName, String objectKey, String filePath){
    try {
        Path path = Paths.get(filePath);
        PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        client.putObject(putObjectRequest, path);
    } catch (Exception e){
        e.printStackTrace();
    }
}

파일 다운로드
// objectKey : 다운로드할 파일명
// filePath : 파일을 내려받을 로컬 경로 및 파일명
private void downloadObject(S3Client client, String bucketName, String objectKey, String filePath){
    try {
        Path path = Paths.get(filePath);
        GetObjectRequest getObjectRequest = GetObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        ResponseBytes<GetObjectResponse> responseBytes = client.getObjectAsBytes(getObjectRequest);

        byte[] data = responseBytes.asByteArray();

        File myFile = new File(filePath);
        OutputStream os = new FileOutputStream(myFile);
        os.write(data);
        os.close();
    } catch (IOException ex) {
        ex.printStackTrace();
    } catch (S3Exception e){
        e.printStackTrace();
    }
}

파일 삭제
// objectKey : 삭제할 파일명
private void deleteObject(S3Client client, String bucketName, String objectKey){
    try {
        DeleteObjectRequest deleteObjectRequest = DeleteObjectRequest.builder()
                .bucket(bucketName)
                .key(objectKey)
                .build();

        client.deleteObject(deleteObjectRequest);

    } catch (Exception e){
        e.printStackTrace();
    }
}

Type 4. Go SDK 예제

AWS Go SDK를 이용하여 카카오클라우드 Object Storage를 이용하는 예시입니다.

S3 클라이언트 생성 및 설정

다음 명령어를 이용하여 로컬 프로젝트를 초기화합니다.
```
$ go mod init {project_name}
```

Go 모듈을 이용하여 Go V2용 AWS SDK 패키지들을 가져옵니다.

$ go get github.com/aws/aws-sdk-go-v2/config
$ go get github.com/aws/aws-sdk-go-v2/credentials
$ go get github.com/aws/aws-sdk-go-v2/service/s3

클라이언트에 사용자 자격 증명 및 환경 정보를 설정합니다.

var accessKeyId = "{S3_ACCESS_KEY}"
var accessKeySecret = "{S3_SECRET_ACCESS_KEY}"
var endpoint = "{ENDPOINT}"
var region = "kr-central-2"
resolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
    return aws.Endpoint{
        URL: endpoint,
    }, nil
})

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion(region),
    config.WithEndpointResolverWithOptions(resolver),
    config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider(accessKeyId, accessKeySecret, "")),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg, func(options *s3.Options) {
    options.UsePathStyle = true
})

SDK 사용 예시

버킷 생성
bucketname := "{BUCKET_NAME}"
_, err = client.CreateBucket(context.TODO(), &s3.CreateBucketInput{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

전체 버킷 목록 조회
_, err = client.ListBuckets(context.TODO(), &s3.ListBucketsInput{})
if err != nil {
    log.Fatal(err)
}

특정 버킷 내부 조회
bucketname := "{BUCKET_NAME}"
_, err = client.ListObjectsV2(context.TODO(), &s3.ListObjectsV2Input{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

버킷 삭제
bucketname := "{BUCKET_NAME}"
_, err = client.DeleteBucket(context.TODO(), &s3.DeleteBucketInput{
    Bucket: &bucketname,
})
if err != nil {
    log.Fatal(err)
}

파일 업로드
bucketname := "{BUCKET_NAME}"
filePath := "{LOCAL_PATH}" // 업로드할 파일이 위치한 로컬 경로
objectKey := "{FILE_NAME}" // 업로드할 파일명

file, err := os.Open(filePath)
if err != nil {
	log.Fatal(err)
}
defer file.Close()

_, err = client.PutObject(context.TODO(), &s3.PutObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
	Body:   file,
})
if err != nil {
    log.Fatal(err)
}

파일 다운로드
bucketname := "{BUCKET_NAME}"
filePath := "{LOCAL_PATH}" // 파일을 내려받을 로컬 경로 및 파일 이름
objectKey := "{FILE_NAME}" // 다운로드할 파일명

file, err := os.Create(filePath)
if err != nil {
	panic(err)
}
defer file.Close()

result, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
})
if err != nil {
	log.Fatal(err)
}

_, err = io.Copy(file, result.Body)
if err != nil {
	panic(err)
}

파일 삭제
bucketname := "{BUCKET_NAME}"
objectKey := "{FILE_NAME}" // 삭제할 파일명

_, err = client.DeleteObject(context.TODO(), &s3.DeleteObjectInput{
	Bucket: &bucketname,
	Key:    &objectKey,
})
if err != nil {
	log.Fatal(err)
}

시나리오 소개​

시작하기 전에​

S3 액세스 키 발급​

Type 1. AWS CLI 예제​

AWS CLI 설정​

AWS CLI 사용 예시​

Type 2. Python SDK(Boto3) 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

Type 3. Java SDK 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

Type 4. Go SDK 예제​

S3 클라이언트 생성 및 설정​

SDK 사용 예시​

시나리오 소개

시작하기 전에

S3 액세스 키 발급

Type 1. AWS CLI 예제

AWS CLI 설정

AWS CLI 사용 예시

Type 2. Python SDK(Boto3) 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시

Type 3. Java SDK 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시

Type 4. Go SDK 예제

S3 클라이언트 생성 및 설정

SDK 사용 예시