--- title: "Object Storage" slug: "guide-objectstorage" tags: ["Object Storage", "CLI"] updated: 2026-05-21T09:02:08Z published: 2026-05-21T09:10:09Z canonical: "cli-gov.ncloud-docs.com/guide-objectstorage" --- > ## Documentation Index > Fetch the complete documentation index at: https://cli-gov.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # Object Storage Classic/VPC 환경에서 이용 가능합니다. 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/](https://pypi.org/project/awscli/1.15.85/) - git: [https://github.com/aws/aws-cli/tree/1.15.85](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 가이드](https://api-gov.ncloud-docs.com/docs/storage-objectstorage)를 참고해 주십시오. ## 명령어 도움말 Object Storage CLI의 원활한 사용을 위해 도움말을 확인하려면 다음 명령어를 실행해 주십시오. ``` aws help aws help aws help ``` ## 명령어 Object Storage CLI를 설명합니다. ### 버킷 생성 버킷을 생성하는 명령어은 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 mb s3:// ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api create-bucket --bucket ``` 참고 awscli 2 버전의 경우, 버킷 생성 명령어(mb) 수행 시 `--region us-east-1` 옵션이 필요합니다. ### 버킷 목록 조회 버킷 목록을 조회하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 ls ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api list-buckets ``` ### 오브젝트 목록 조회 #### 전체 오브젝트 목록 조회 전체 오브젝트 목록을 조회하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 ls s3:// ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api list-objects --bucket ``` #### 특정 문자열을 포함한 오브젝트 조회 오브젝트 이름에 특정 문자열(예: foo)을 포함하는 오브젝트 목록을 조회하는 명령어는 다음과 같습니다. - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api list-objects --bucket --prefix --query "Contents[?contains(Key, 'foo')]" ``` ### 크기 조회 #### 버킷 크기 조회 버킷 크기 조회를 위한 옵션은 high-level 명령으로만 수행할 수 있습니다. 버킷 크기를 조회하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 ls s3:// --recursive --human-readable --summarize ``` #### 폴더 크기 조회 폴더 크기 조회를 위한 옵션은 high-level 명령으로만 수행할 수 있습니다. 폴더 크기를 조회하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 ls s3:/// --recursive --human-readable --summarize ``` ### 오브젝트 업로드 오브젝트를 업로드하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 cp s3://[/] ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api put-object --bucket --key --body ``` ### 멀티파트 업로드 아래 순서대로 진행해야 정상적으로 멀티파트 업로드가 가능합니다. 1. 멀티파트 업로드 시작 아래 명령을 통해 UploadId 값을 생성하고 반환합니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api create-multipart-upload --bucket --key ``` 2. 멀티파트 업로드 아래 명령을 통해 파트를 업로드하고 업로드한 파트의 ETag 값을 반환합니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api upload-part --bucket --key --part-number --body --upload-id ``` 3. 멀티파트 업로드 완료 아래 명령을 통해 위에서 업로드한 파트들의 멀티파트 업로드를 완료합니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api complete-multipart-upload --bucket --key --upload-id --multipart-upload file:// ``` - `json_file` 예제: ``` { "Parts": [ {"ETag": "90e6f8b09862bb7fdc080c89d53dbc65", "PartNumber": 1}, {"ETag": "f158dfe47ee46ce22a80986cf8f4bdbb", "PartNumber": 2}, ...... {"ETag": "7d29c5f2bc97aebc6a395b52a0fb9d88", "PartNumber": 7} ] } ``` ### 오브젝트 삭제 오브젝트를 삭제하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 rm s3:/// ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api delete-object --bucket --key ``` ### 버킷/폴더 내 모든 오브젝트 삭제 버킷 또는 폴더 내 모든 오브젝트를 삭제하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 rm s3:///[/] --recursive ``` ### 미완료 멀티파트 업로드 삭제 아래 방법으로 미완료 멀티파트 업로드가 있는지 확인하고, 미완료 멀티파트 업로드를 삭제할 수 있습니다. 1. 미완료 멀티파트 업로드 조회 아래 명령을 통해 완료되지 않은 멀티파트 업로드 정보를 조회합니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api list-multipart-uploads --bucket ``` 2. 미완료 멀티파트 업로드 삭제 아래 명령을 통해 위에서 조회한 `upload_id` 를 입력하여 미완료 멀티파트 업로드를 삭제할 수 있습니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api abort-multipart-uploads --bucket --key --upload-id ``` ### 버킷 삭제 버킷을 삭제하는 명령어는 다음과 같습니다. - high-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 rb s3:// ``` force 옵션을 추가하면 비어있지 않은 버킷을 삭제할 수 있습니다. 버킷에 속해있는 오브젝트를 모두 삭제한 후 버킷을 삭제합니다. ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 rb s3:// --force ``` - API-level ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api delete-bucket --bucket ``` 참고 API-level의 경우 비어있지 않은 버킷을 삭제할 수 없습니다. ### 동기화 동기화 기능은 high-level 명령으로만 수행할 수 있습니다. *--delete* 옵션을 사용하면 source에 없는 파일은 destination에서 삭제합니다. 동기화 명령어는 다음과 같습니다. - high-level - Object Storage의 버킷(폴더)의 모든 파일을 로컬에 동기화 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 sync s3://[/] ``` - 로컬 디렉토리의 모든 파일을 Object Storage의 버킷(폴더)에 동기화 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 sync s3://[/] ``` - Object Storage의 버킷(폴더)의 모든 파일을 다른 버킷(폴더)에 동기화 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 sync s3://[/] s3://[/] ``` ### 접근 제어 목록(ACL) Object Storage 버킷(폴더)의 파일에 대한 접근 제어 목록(ACL)권한을 설정할 수 있습니다. 접근 제어 목록 기능은 API-level 명령으로만 수행할 수 있습니다. 명령어는 다음과 같습니다. - API-level - Object Storage 버킷의 파일을 [공개]로 설정 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api put-object-acl --bucket --key --acl public-read ``` - Object Storage 버킷의 파일을 [공개 안함]으로 설정 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3api put-object-acl --bucket --key --acl private ``` 목록 조회 명령어(ls)와 함께 사용하면 Object Storage 버킷(폴더)에 업로드된 모든 파일을 공개로 설정할 수 있습니다. 명령어는 다음과 같습니다. - Object Storage 버킷의 모든 파일을 [공개]로 설정 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com/ s3 ls s3:// --recursive | awk '{cmd="aws --endpoint-url=https://kr.object.gov-ncloudstorage.com/ s3api put-object-acl --bucket --acl public-read --key "$4; system(cmd)}' ``` 주의 버킷의 모든 파일에 대해 공개 설정이 되기 때문에 명령어 수행 시 유의바랍니다. ### 디버깅 디버깅 관련 명령어는 다음과 같습니다. - --debug* 옵션을 사용하여 자세한 로그 확인 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 cp s3://[/] --debug ``` - 로그 파일로 저장 ``` aws --endpoint-url=https://kr.object.gov-ncloudstorage.com s3 cp s3://[/] --debug 2> debug.log ```