release/20250417
- release/20250320
- release/20250417

Object Storage CLI

인쇄
공유
PDF

Object Storage CLI

인쇄
공유
PDF

기사 요약

이 요약이 도움이 되었나요?

의견을 보내 주셔서 감사합니다.

Amazon S3 CLI와 호환되는 Object Storage CLI의 초기 설정 방법부터 간단한 사용 방법 등을 확인합니다.

초기 설정

Object Storage CLI를 사용하기 위한 설치와 인증 방법을 설명합니다.

설치

설치 명령어는 다음과 같습니다.

pip install awscli==1.15.85

참고

awscli 1.16.x 버전은 일부 기능을 미지원하므로 1.15.x 버전 사용을 권장합니다.
awscli 1.15.85 버전은 Python 3.8 이하 버전을 지원합니다.
관련 자료는 다음을 참고해 주십시오.
- 문서: https://pypi.org/project/awscli/1.15.85/
- git: https://github.com/aws/aws-cli/tree/1.15.85

인증

인증 정보를 설정하는 방법은 다음과 같습니다.

~$ aws configure
AWS Access Key ID [****************leLy]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_KEY
Default region name [None]: [Enter]
Default output format [None]: [Enter]

주의 사항

Role을 부여받은 서버에서 사용 시 주의해야 할 내용을 설명합니다. Role을 부여받은 서버는 별도의 configure 없이 Object Storage 명령을 사용할 수 있습니다.
Role을 부여받은 서버에서 사용 시 Metadata API 중 인증키 조회 API를 사용합니다. 단, 이 과정에서 timeout이 발생할 수 있기 때문에 필요한 경우 다음 명령을 통해 Metadata API timeout을 연장하여 사용할 수 있습니다.

export AWS_METADATA_SERVICE_TIMEOUT=10

CLI 이용 시 --endpoint-url 옵션은 필수값입니다. 리전별 호출 도메인은 Object Storage API 가이드를 참고해 주십시오.

명령어 도움말

Object Storage CLI의 원활한 사용을 위해 도움말을 확인하려면 다음 명령어를 실행해 주십시오.

aws help
aws <command> help
aws <command> <subcommand> help

명령어

Object Storage CLI를 설명합니다.

버킷 생성

버킷을 생성하는 명령어은 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 mb s3://<bucket_name>

API-level
```
aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api create-bucket --bucket <bucket_name>
```
참고
awscli 2 버전의 경우, 버킷 생성 명령어(mb) 수행 시 --region us-east-1 옵션이 필요합니다.

버킷 목록 조회

버킷 목록을 조회하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 ls

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api list-buckets

오브젝트 목록 조회

전체 오브젝트 목록 조회

전체 오브젝트 목록을 조회하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 ls s3://<bucket_name>

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api list-objects --bucket <bucket_name>

특정 문자열을 포함한 오브젝트 조회

오브젝트 이름에 특정 문자열(예: foo)을 포함하는 오브젝트 목록을 조회하는 명령어는 다음과 같습니다.

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api list-objects --bucket <bucket_name> --prefix <prefix> --query "Contents[?contains(Key, 'foo')]"

크기 조회

버킷 크기 조회

버킷 크기 조회를 위한 옵션은 high-level 명령으로만 수행할 수 있습니다. 버킷 크기를 조회하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 ls s3://<bucket_name> --recursive --human-readable --summarize

폴더 크기 조회

폴더 크기 조회를 위한 옵션은 high-level 명령으로만 수행할 수 있습니다. 폴더 크기를 조회하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 ls s3://<bucket_name>/<folder_name> --recursive --human-readable --summarize

오브젝트 업로드

오브젝트를 업로드하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 cp <local_file_path> s3://<bucket_name>[/<object_name>]

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api put-object --bucket <bucket_name> --key <object_name> --body <local_file_path>

멀티파트 업로드

아래 순서대로 진행해야 정상적으로 멀티파트 업로드가 가능합니다.

멀티파트 업로드 시작
아래 명령을 통해 UploadId 값을 생성하고 반환합니다.

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api create-multipart-upload --bucket <bucket_name> --key <object_name>

멀티파트 업로드
아래 명령을 통해 파트를 업로드하고 업로드한 파트의 ETag 값을 반환합니다.

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api upload-part --bucket <bucket_name> --key <object_name> --part-number <sequential_integer> --body <local_file_path> --upload-id <upload_id>

멀티파트 업로드 완료
아래 명령을 통해 위에서 업로드한 파트들의 멀티파트 업로드를 완료합니다.

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api complete-multipart-upload --bucket <bucket_name> --key <object_name> --upload-id <upload_id> --multipart-upload file://<json_file>

json_file 예제:

{
  "Parts": [
    {"ETag": "90e6f8b09862bb7fdc080c89d53dbc65", "PartNumber": 1},
    {"ETag": "f158dfe47ee46ce22a80986cf8f4bdbb", "PartNumber": 2},
     ......
    {"ETag": "7d29c5f2bc97aebc6a395b52a0fb9d88", "PartNumber": 7}
  ]
}

오브젝트 다운로드

오브젝트를 다운로드하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=http://kr.object.fin-ncloudstorage.com s3 cp s3://<bucket_name>/<object_name> <local_file_path>

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api get-object --bucket <bucket_name> --key <object_name> <local_file_path>

오브젝트 삭제

오브젝트를 삭제하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 rm s3://<bucket_name>/<object_name>

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api delete-object --bucket <bucket_name> --key <object_name>

버킷/폴더 내 모든 오브젝트 삭제

버킷 또는 폴더 내 모든 오브젝트를 삭제하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 rm s3://<bucket_name>/[<folder_name>/] --recursive

미완료 멀티파트 업로드 삭제

아래 방법으로 미완료 멀티파트 업로드가 있는지 확인하고, 미완료 멀티파트 업로드를 삭제할 수 있습니다.

미완료 멀티파트 업로드 조회
아래 명령을 통해 완료되지 않은 멀티파트 업로드 정보를 조회합니다.
```
aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api list-multipart-uploads --bucket <bucket_name>
```
미완료 멀티파트 업로드 삭제
아래 명령을 통해 위에서 조회한 upload_id 를 입력하여 미완료 멀티파트 업로드를 삭제할 수 있습니다.
```
aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api abort-multipart-uploads --bucket <bucket_name> --key <object_name> --upload-id <upload_id>
```

버킷 삭제

버킷을 삭제하는 명령어는 다음과 같습니다.

high-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 rb s3://<bucket_name>

force 옵션을 추가하면 비어있지 않은 버킷을 삭제할 수 있습니다. 버킷에 속한 오브젝트를 모두 삭제한 후 버킷을 삭제합니다.

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 rb s3://<bucket_name> --force

API-level

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api delete-bucket --bucket <bucket_name>

참고

API-level의 경우 비어있지 않은 버킷을 삭제할 수 없습니다.

동기화

동기화 기능은 high-level 명령으로만 수행할 수 있습니다. --delete 옵션을 사용하면 source에 없는 파일은 destination에서 삭제합니다. 동기화 명령어는 다음과 같습니다.

high-level

Object Storage의 버킷(폴더)의 모든 파일을 로컬에 동기화

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 sync s3://<bucket_name>[/<object_name>] <local_directory_name>

로컬 디렉토리의 모든 파일을 Object Storage의 버킷(폴더)에 동기화

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 sync <local_directory_name> s3://<bucket_name>[/<object_name>]

Object Storage의 버킷(폴더)의 모든 파일을 다른 버킷(폴더)에 동기화
```
aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 sync s3://<source_bucket_name>[/<destination_object_name>] s3://<destination_bucket_name>[/<destination_object_name>]
```
참고
awscli 2 버전의 경우, 동기화 명령 수행 시 지원하지 않는 api를 호출하여 에러가 발생할 수 있으므로 1.15.x 버전 사용을 권장합니다.

접근 제어 목록(ACL)

Object Storage 버킷(폴더)의 파일에 대한 접근 제어 목록(ACL)권한을 설정할 수 있습니다. 접근 제어 목록 기능은 API-level 명령으로만 수행할 수 있습니다. 명령어는 다음과 같습니다.

API-level

Object Storage 버킷의 파일을 공개로 설정

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api put-object-acl --bucket <bucket_name> --key <object_name> --acl public-read

Object Storage 버킷의 파일을 공개 안함으로 설정

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api put-object-acl --bucket <bucket_name> --key <object_name> --acl private

목록 조회 명령어(ls)와 함께 사용하면 Object Storage 버킷(폴더)에 업로드된 모든 파일을 공개로 설정할 수 있습니다. 명령어는 다음과 같습니다.

Object Storage 버킷의 모든 파일을 공개로 설정

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com/ s3 ls s3://<bucket_name> --recursive | awk '{cmd="aws --endpoint-url=https://kr.object.fin-ncloudstorage.com/ s3api put-object-acl --bucket <bucket_name> --acl public-read --key "$4; system(cmd)}'

주의

버킷의 모든 파일에 대해 공개 설정이 되기 때문에 명령어 수행 시 유의바랍니다.

디버깅

디버깅 관련 명령어는 다음과 같습니다.

--debug* 옵션을 사용하여 자세한 로그 확인

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 cp <local_file_path> s3://<bucket_name>[/<object_name>] --debug

로그 파일로 저장

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3 cp <local_file_path> s3://<bucket_name>[/<object_name>] --debug 2> debug.log

CORS 설정

Object Storage 버킷에 대해 CORS(Cross-Origin Resource Sharing)를 설정합니다. Object Storage 버킷에서 교차 출처 요청을 수신하면 CORS 구성을 확인하고 브라우저 요청과 일치하는 첫번째 CORS 규칙을 사용하여 교차 출처 요청을 허용합니다. CORS 규칙과 일치하려면 다음 사항을 충족해야 합니다.

요청의 Origin 헤더는 AllowedOrigins 요소와 일치해야 합니다.
요청 method 또는 Access-Control-Request-Method 헤더(Preflight 요청)는 AllowedMethods 요소와 일치해야 합니다.
Access-Control-Request-Headers 헤더(Preflight 요청)에 지정된 모든 헤더는 AllowedHeaders 요소와 일치해야 합니다. CORS 설정은 API-level 명령으로만 수행할 수 있습니다.

명령어는 다음과 같습니다.

API-level

json 파일로 정의한 CORS 규칙을 Object Storage 버킷에 설정

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api put-bucket-cors --bucket <bucket_name> --cors-configuration file://cors.json

cors.json:
{
  "CORSRules": [
  {
      "AllowedHeaders": ["*"],
      "AllowedMethods": ["GET","PUT"],
      "AllowedOrigins": ["*"],
      "MaxAgeSeconds": 3000
    }
  ]
}

Object Storage 버킷에 설정된 CORS 규칙 조회

aws --endpoint-url=https://kr.object.fin-ncloudstorage.com s3api get-bucket-cors --bucket <bucket_name>

Object Storage CLI

초기 설정

설치

인증

주의 사항

명령어 도움말

명령어

버킷 생성

버킷 목록 조회

오브젝트 목록 조회

전체 오브젝트 목록 조회

특정 문자열을 포함한 오브젝트 조회

크기 조회

버킷 크기 조회

폴더 크기 조회

오브젝트 업로드

멀티파트 업로드

오브젝트 다운로드

오브젝트 삭제

버킷/폴더 내 모든 오브젝트 삭제

미완료 멀티파트 업로드 삭제

버킷 삭제

동기화

접근 제어 목록(ACL)

디버깅

CORS 설정

What's Next