[Management Tool] CLI를 활용한 S3 구성 가이드

개요

AWS Management Console에서의 수동 조작은 반복 작업이 많고 대규모 작업 처리에 한계가 있습니다.
이때 AWS CLI는 명령어 기반으로 S3를 제어할 수 있어 자동화, 대량 처리, 스크립트 기반 운영 등에 매우 유리합니다.
S3 CLI 명령어인 cp, sync, mv, rm 등을 활용하면 수백 개의 파일을 빠르게 복사하거나 정리할 수 있으며,
고급 설정을 통해 성능을 조정하거나 네트워크 제한을 설정할 수도 있습니다.
이 글에서는 S3 CLI의 설치부터 고급 설정까지 단계적으로 안내합니다.

---

AWS CLI 설치 및 구성

공식 문서: AWS CLI 설치 가이드

1. AWS CLI 설치

Windows (64비트):

• 설치 파일 다운로드 및 실행:
• AWS CLI MSI 설치 파일
• 명령줄에서 설치:

C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi

• 무인 설치(옵션):

C:\> msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi /qn

• 설치 확인:

C:\> aws --version

macOS:

• Homebrew 사용 시:

brew install awscli

Linux (x86_64):

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

• 기존 설치 업데이트:

sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update

Linux (ARM, aarch64):

curl "https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

• 기존 설치 업데이트:

sudo ./aws/install --bin-dir /usr/local/bin --install-dir /usr/local/aws-cli --update

• 설치 확인:

aws --version

---

2. 설치 오류 대처법

설치 또는 설정 중 문제가 발생했을 경우 아래 항목을 확인해보세요.

aws 명령어가 인식되지 않는 경우

• 터미널에서 aws --version 명령어 실행 시 'command not found'가 발생한다면:
  • CLI가 설치된 경로가 PATH 환경 변수에 포함되어 있는지 확인합니다.
  • 일반적으로 Linux에서는 ~/.local/bin, Windows에서는 C:\Program Files\Amazon\AWSCLIV2 경로가 포함되어야 합니다.
  • Linux의 경우 다음 명령어로 경로 추가:

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

unzip 명령어 없음

• Linux에서 CLI zip 설치 시 unzip: command not found 오류 발생:

sudo apt install unzip -y  # Ubuntu
sudo yum install unzip -y  # Amazon Linux

퍼미션 오류

• sudo ./aws/install 시 권한 오류가 발생하는 경우:
  • 관리자 권한이 없거나 디스크 경로 권한 문제가 있을 수 있습니다.
  • sudo 권한이 필요한 경우 sudo su로 루트로 전환하거나 관리자에게 권한 요청하세요.

Windows에서 CLI 실행이 안 될 때

• 설치 후에도 aws 명령어가 인식되지 않는다면:
  • 명령 프롬프트를 완전히 종료 후 재실행해야 환경변수 반영됨
  • C:\Program Files\Amazon\AWSCLIV2\가 PATH에 포함되어 있는지 확인
  • setx PATH "%PATH%;C:\Program Files\Amazon\AWSCLIV2" 로 수동 등록 가능

설치 버전 충돌 또는 이전 버전이 삭제되지 않음

• which aws 또는 where aws (Windows) 명령어로 현재 등록된 CLI 위치를 확인 후, 이전 버전을 수동 삭제하고 새 버전으로 재설치하세요.

3. AWS CLI 구성

aws configure

입력 항목:

• AWS Access Key ID
• AWS Secret Access Key
• Default region name (예: ap-northeast-2)
• Default output format (json, table, text)

---

S3 구성 설정

1. 버킷 생성

aws s3 mb s3://my-bucket-name

2. 객체 목록 조회

aws s3 ls
aws s3 ls s3://my-bucket-name

3. 파일 업로드 및 다운로드

aws s3 cp localfile.txt s3://my-bucket-name/
aws s3 cp s3://my-bucket-name/remotefile.txt .

4. 동기화

aws s3 sync ./local-dir s3://my-bucket-name/

---

고급 설정 및 최적화

~/.aws/config 파일 예시:

[profile development]
s3 =
  max_concurrent_requests = 20
  max_queue_size = 10000
  multipart_threshold = 64MB
  multipart_chunksize = 16MB
  max_bandwidth = 50MB/s
  use_accelerate_endpoint = true
  addressing_style = path

AWS CLI 명령어로 설정하는 방법:

aws configure set default.s3.max_concurrent_requests 20
aws configure set default.s3.max_queue_size 10000
aws configure set default.s3.multipart_threshold 64MB
aws configure set default.s3.multipart_chunksize 16MB
aws configure set default.s3.max_bandwidth 50MB/s
aws configure set default.s3.use_accelerate_endpoint true
aws configure set default.s3.addressing_style path

---

구성 가능한 세부 파라미터 설명

설정 항목	설명
max_concurrent_requests	동시 요청 수 설정 (기본값: 10). 너무 많으면 시스템 리소스 과부하, 적으면 전송 지연.
max_queue_size	S3 전송 작업을 대기열에 쌓을 수 있는 최대 수 (기본값: 1000). 대규모 처리에 유용.
multipart_threshold	멀티파트 전송을 시작하는 파일 크기 임계값 (기본값: 8MB). 10MB 이상 권장.
multipart_chunksize	각 멀티파트 전송의 조각 크기 (기본값: 8MB, 최소 5MB). 클수록 성능 향상 가능.
max_bandwidth	최대 네트워크 사용량 제한 설정. 예: 50MB/s, 300KB/s.
use_accelerate_endpoint	S3 Accelerate 엔드포인트 사용 여부 (기본값: false). 버킷에서 활성화 필요.
use_dualstack_endpoint	IPv4/IPv6 DualStack 엔드포인트 사용 여부. Accelerate와 동시 사용 불가.
addressing_style	S3 주소 방식 설정. path, virtual, auto 중 선택. 기본값: auto.
payload_signing_enabled	요청에 SHA256 서명 포함 여부. 스트리밍 업로드 시 성능 영향 있음.

---

참고 문서

• AWS CLI S3 구성 공식 문서
• AWS CLI 상위 수준(s3) 명령
• AWS CLI 자격 증명 설정
• AWS CLI 설치 가이드