본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Cloudflare R2 CLI

원문 보기 위키 갱신

R2 버킷과 객체를 터미널에서 직접 관리할 수 있어요. CLI 도구를 사용하면 작업을 자동화하고 객체를 관리하기 좋아요.

출처: 문서

본문

도구 가장 좋은 용도
Wrangler 최소한의 설정으로 단일 객체 작업과 버킷 설정 관리
rclone 대량 객체 작업, 마이그레이션, 디렉터리 동기화
AWS CLI 기존 AWS 워크플로우를 쓰거나 AWS CLI에 익숙한 경우

1. 버킷 생성하기

버킷은 R2에서 객체를 저장하는 곳이에요. 새 R2 버킷을 만들려면:

  1. Cloudflare 계정에 로그인해요:

    npx wrangler login

  2. my-bucket이라는 이름의 버킷을 만들어요:

    npx wrangler r2 bucket create my-bucket

    요청이 나오면 버킷을 만들 계정을 선택해요.

  3. 버킷이 생성됐는지 확인해요:

    npx wrangler r2 bucket list

또는 Cloudflare Dashboard에서 만들 수도 있어요.

  1. Cloudflare Dashboard의 R2 object storage로 이동해요. Overview로 이동
  2. Create bucket을 선택해요.
  3. 버킷 이름을 입력해요.
  4. 버킷의 location과 default storage class를 선택해요.
  5. Create bucket을 선택해요.

2. API 자격 증명 생성하기

S3 API를 사용하는 CLI 도구(AWS CLI, rclone)에는 Access Key ID와 Secret Access Key가 필요해요. Wrangler를 사용한다면 이 단계는 건너뛰어도 돼요.

  1. Cloudflare dashboard에서 R2로 이동해요.
  2. Manage R2 API tokens을 선택해요.
  3. Create API token을 선택해요.
  4. Object Read & Write 권한을 선택하고 접근하려는 버킷을 선택해요.
  5. Create API Token을 선택해요.
  6. Access Key ID와 Secret Access Key를 복사해요. 시크릿 키는 다시 볼 수 없으니 안전하게 보관해요.

3. CLI 도구 설정하기

Wrangler는 Cloudflare Workers CLI예요. Cloudflare 계정으로 직접 인증하므로 API 자격 증명이 필요 없어요.

  1. Wrangler를 설치해요:

    npm i -D wrangler

    yarn add -D wrangler

    pnpm add -D wrangler

    bun add -d wrangler

  2. Cloudflare 계정에 로그인해요:

    wrangler login

rclone은 대량 업로드, 마이그레이션, 디렉터리 동기화에 이상적이에요.

  1. rclone 설치(버전 1.59 이상).

  2. 새 remote를 구성해요:

    rclone config

  3. n을 선택해 새 remote를 만들어요.

  4. remote 이름을 r2로 정해요.

  5. 저장소 유형으로 Amazon S3 Compliant Storage Providers를 선택해요.

  6. 프로바이더로 Cloudflare R2를 선택해요.

  7. AWS 자격 증명을 직접 입력할지, 런타임 환경에서 가져올지 선택해요.

  8. 요청이 나오면 Access Key ID와 Secret Access Key를 입력해요.

  9. 연결할 region을 선택해요(선택 사항).

  10. S3 API 엔드포인트를 입력해요.

AWS CLI는 커스텀 엔드포인트를 지정해 R2와 함께 동작해요.

  1. 운영체제에 맞는 AWS CLI를 설치해요.

  2. 자격 증명을 구성해요:

    aws configure

  3. 요청이 나오면 다음을 입력해요:

    • AWS Access Key ID: R2 Access Key ID
    • AWS Secret Access Key: R2 Secret Access Key
    • Default region name: auto
    • Default output format: json (또는 Enter를 눌러 건너뛰기)

4. 객체 업로드·다운로드하기

(선택 사항) 업로드할 테스트 파일을 만들어요. CLI 명령을 실행할 디렉터리에서 실행해요:

echo 'Hello, R2!' > myfile.txt

# myfile.txt를 my-bucket에 업로드
wrangler r2 object put my-bucket/myfile.txt --file ./myfile.txt

# myfile.txt를 다운로드해 downloaded.txt로 저장
wrangler r2 object get my-bucket/myfile.txt --file ./downloaded.txt

사용 가능한 모든 작업은 Wrangler R2 commands를 참고해요.

# myfile.txt를 my-bucket에 업로드
rclone copy myfile.txt r2:my-bucket/

# myfile.txt를 my-bucket에서 현재 디렉터리로 다운로드
rclone copy r2:my-bucket/myfile.txt .

더 많은 구성 옵션은 rclone documentation을 참고해요.

# myfile.txt를 my-bucket에 업로드
aws s3 cp myfile.txt s3://my-bucket/ --endpoint-url https://<ACCOUNT_ID>.r2.cloudflarestorage.com

# myfile.txt를 my-bucket에서 현재 디렉터리로 다운로드
aws s3 cp s3://my-bucket/myfile.txt ./ --endpoint-url https://<ACCOUNT_ID>.r2.cloudflarestorage.com

# my-bucket의 모든 객체 나열
aws s3 ls s3://my-bucket/ --endpoint-url https://<ACCOUNT_ID>.r2.cloudflarestorage.com

더 많은 예시는 AWS CLI documentation을 참고해요.

다음 단계

  • Presigned URLs — 비공개 객체 접근을 위한 임시 URL 생성하기
  • Public buckets — 공개 버킷으로 파일을 HTTP로 직접 제공하기
  • CORS — 브라우저 기반 업로드를 위한 CORS 구성하기
  • Object lifecycles — 오래된 객체를 자동 삭제하는 수명주기 규칙 설정하기

더 알아보기 (Learn more)

CLI 시작 후에는 Presigned URLs, Public buckets, CORS, Object lifecycles 문서로 넘어가 보세요.