[MinIO] mc(minio client) 사용법

개요

MinIO는 고성능의 오브젝트 스토리지로, Amazon S3와 호환되는 API를 제공합니다.

 

MinIO Client(mc)는 이러한 MinIO 서버를 관리하고 데이터를 다루기 위한 커맨드라인 도구로, 파일 업로드/다운로드, 서버 상태 모니터링, 사용자 및 정책 관리, 데이터 복제, 수명주기 관리(ILM), 암호화 및 이벤트 알림 설정 등 운영에 필요한 다양한 기능을 지원합니다.

 

이번 글에서는 mc의 초기 설정부터 버킷 및 객체 관리, 데이터 보호 및 복제, 보안 정책 설정, 이벤트 알림 구성까지 실무에서 자주 활용되는 명령어를 설명하고, 실습 예시를 통해 IAM 정책 설정과 사용자 권한 테스트를 진행합니다.

 

mc 설치

 

1. 리눅스

# 최신 mc 바이너리 다운로드
curl --progress-bar -L https://dl.min.io/aistor/mc/release/linux-amd64/mc --create-dirs -o $HOME/aistor-binaries/mc

# 실행 권한 부여
chmod +x ~/aistor-binaries/mc

# PATH 등록 (예: /usr/local/bin)
sudo mv ~/aistor-binaries/mc /usr/local/bin/

 

2. 윈도우

# 최신 mc.exe 다운로드
Invoke-WebRequest https://dl.min.io/aistor/mc/release/windows-amd64/mc -OutFile C:\mc.exe
C:\mc.exe --help

 

3. 맥

#최신 mc 바이너리 다운로드
curl --progress-bar -L https://dl.min.io/aistor/mc/release/darwin-arm64/mc --create-dirs -o ~/aistor-binaries/mc

#실행 권한 부여
chmod +x ~/aistor-binaries/mc

#PATH 등록
~/aistor-binaries/mc --help

 

 

참고 : Audit Logging | AIStor Object Store Documentation

 

명령어 정리

mc commands list

 

MinIO 서버 초기 설정
mc alias set	MinIO 서버에 접근하기 위한 별칭(alias)을 등록합니다.
	한 서버에 여러 별칭을 등록할 수 있으며, 외부 서버도 등록하여 운영 목적에 맞게 활용할 수 있습니다.
mc alias list	현재 등록된 서버 별칭(alias) 목록을 조회합니다.
mc alias remove	등록된 서버 별칭(alias)을 제거합니다.
mc admin info	MinIO 서버 또는 클러스터 정보를 조회합니다.
mc config set	클라이언트 설정 값을 추가하거나 변경합니다.

 

Bucket/Object 관리
mc ls	버킷 또는 객체 목록을 조회합니다.
mc stat	버킷 또는 객체의 상세 메타데이터를 확인합니다.
mc tree	버킷 내부 객체 구조를 트리 형태로 출력합니다.
mc cat	객체 내용을 표준 출력으로 확인합니다.
mc du	버킷 또는 경로별 용량 사용량을 계산합니다.
mc mb	새로운 버킷을 생성합니다.
mc tag	객체 또는 버킷에 태그를 부여하거나 조회합니다.
mc mv	객체를 다른 위치로 이동하거나 이름을 변경합니다.
mc get	MinIO 서버에 있는 객체를 로컬로 다운로드 합니다.
mc rb	버킷을 삭제합니다. (사용 중인 버킷은 삭제되지 않습니다.)
mc share	객체 또는 버킷에 대한 접근 링크를 생성하여 공유합니다.

 

데이터 보호/안전성
mc cp	객체를 다른 경로에 복사합니다. (로컬 ↔ MinIO, MinIO ↔ MinIO 모두 지원)
	단순 복사 명령으로, 기존 대상에 이미 동일한 객체가 있으면 덮어쓰거나 건너뛸 수 있습니다.
mc mirror	버킷 또는 디렉토리를 다른 경로와 동기화합니다.
	변경 사항만 반영하여 대상과 동기화하므로, 대규모 데이터 이관이나 정기 백업에 적합합니다.
mc replicate	객체 복제를 설정하여 자동으로 관리합니다. (단방향, 양방향 복제 모두 지원)
	버킷 간 자동 복제 정책을 구성하여, 여러 클러스터나 서버에 동일한 데이터를 유지할 수 있습니다.
mc ilm	버킷에 수명주기 관리(ILM) 정책을 설정합니다.
	객체 prefix나 별도로 지정된 tag 기반으로 정책 설정이 가능합니다.
mc version enable	버킷 버저닝을 활성화합니다.
	동일한 이름의 객체가 여러 버전으로 저장되며, 기존 객체를 덮어쓰더라도 이전 버전을 보존합니다.
mc retention	버킷 또는 객체에 보존 정책(compliance/governance 모드)을 설정합니다.
	compliance 설정 시 관리자 포함 정책 변경이 불가합니다.
mc legalhold	객체에 법적 보존 정책을 설정하거나 해제합니다. (retention보다 강력)

 

보안/정책 설정
mc admin user	사용자 계정을 생성, 삭제, 관리합니다. 사용자는 여러 그룹에 속할 수 있습니다.
mc admin user svcacct	사용자 계정에 서비스 계정을 생성하거나 관리합니다. (애플리케이션용 접근 키 발급 시 사용)
mc admin group	사용자 그룹을 생성, 삭제, 관리합니다.
mc admin policy	정책을 생성하거나 수정하고 사용자/그룹에 연결합니다.
	여러 정책이 적용된 경우 가장 보수적인 정책이 우선 적용됩니다.
mc anonymous	버킷 단위 접근 정책을 설정하거나 조회합니다.
	prefix를 지정하여 객체 단위 접근 제어도 가능합니다.
mc encrypt	버킷 단위 서버 측 암호화(SSE)를 설정합니다.

 

이벤트 알림/모니터링
mc event	버킷에 이벤트 알림 구성을 추가하거나 관리합니다. (Kafka, NATS, Webhook 등으로 전송)
mc watch	버킷 또는 객체의 변경 이벤트를 실시간으로 모니터링합니다.
mc admin prometheus	Prometheus 연동을 위해 MinIO 서버 메트릭 엔드포인트를 활성화합니다.

 

 

참고 : MinIO Client — MinIO Object Storage (AGPLv3)

 

---

 

CLI로 실습 진행  - IAM 정책 설정

---

[시나리오]

1. 사전에 설치된 k8sminio 서버 조회 및 mybucket 내 life.txt 파일 확인

 

2. 'devgroup' 그룹 생성 후 'devuser' 사용자 추가

 

3. 버킷 다운로드 제한 정책 'test-policy' 생성 후 실제 동작 확인

k8sminio(root)

└─ devgroup               =>    test-policy 적용 (모든 버킷 조회 허용 / 모든 버킷 다운로드 제한)

     └─ devuser

 

4.기존 정책 삭제 후, 모든 버킷 다운로드 허용 정책 'test-policy-2'설정. 실제 동작 확인

k8sminio(root)

└─ devgroup               =>    test-policy-2 적용 (모든 버킷 조회/다운로드 허용)

     └─ devuser

---

1. 서버 정보/버킷 확인

root@ria:/home/ria# kubectl exec -it -n tenant-0 sts/myminio-pool-0 -c minio -- cat /tmp/minio/config.env
...
export MINIO_ROOT_PASSWORD="minio123"
export MINIO_ROOT_USER="minio"
...

root@ria:/home/ria# mc ls k8sminio --insecure
[2025-09-13 02:50:41 UTC] 0B mybucket/

root@ria:/home/ria# mc tree --files k8sminio/mybucket --insecure
k8sminio/mybucket
└─ life.txt

 

2. 사용자 및 그룹 생성

root@ria:/home/ria# mc admin user add k8sminio devuser devuser123 --insecure
Added user `devuser` successfully.

root@ria:/home/ria# mc admin group add k8sminio devgroup devuser --insecure
Added members `devuser` to group `devgroup` successfully.

 

3. 특정 그룹에 IAM 정책 설정 [Allow : ListAllMyBuckets | Deny : GetObject ]

>> test-policy.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListAllMyBuckets"], "Resource": [ "arn:aws:s3:::*" ] }, { "Effect": "Deny", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::*" ] } ] }

root@ria:/home/ria# mc admin policy create k8sminio test-policy policy.json --insecure
Created policy `test-policy` successfully.

root@ria:/home/ria# mc admin policy attach k8sminio test-policy --group devgroup --insecure
Attached Policies: [test-policy]
To Group: devgroup

root@ria:/home/ria# mc alias set devuser https://127.0.0.1:30002 devuser devuser123 --insecure
Added `devuser` successfully.

---

#버킷 리스트 조회 성공
root@ria:/home/ria# mc ls devuser --insecure
[2025-09-13 02:50:41 UTC] 0B mybucket/


#객체 다운로드 실패
root@ria:/home/ria# mc cp devuser/mybucket/life.txt . --insecure
mc: <ERROR> Unable to prepare URL for copying. Insufficient permissions to access this path `https://127.0.0.1:30002/mybucket/life.txt`

 

4. 정책 변경 [Allow : ListAllMyBuckets, GetObject ]

>> test-policy-2.json
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListAllMyBuckets","s3:GetObject"], "Resource": [ "arn:aws:s3:::*" ] }] }

root@ria:/home/ria# mc admin policy detach k8sminio test-policy --group devgroup --insecure
Detached Policies: [test-policy]
From Group: devgroup

root@ria:/home/ria# mc admin policy create k8sminio test-policy-2 policy-2.json --insecure
Created policy `test-policy-2` successfully.

root@ria:/home/ria# mc admin policy attach k8sminio test-policy-2 --group devgroup --insecure
Attached Policies: [test-policy-2]
To Group: devgroup

---

#버킷 리스트 조회 성공
root@ria:/home/ria# mc ls devuser --insecure
[2025-09-13 02:50:41 UTC] 0B mybucket/


#객체 다운로드 성공
root@ria:/home/ria# mc cp devuser/mybucket/life.txt . --insecure
0 B / ?┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░▓┃...30002/mybucket/life.txt:
65.18 KiB / 65.18 KiB ┃▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓┃ 4.09 MiB/s 0s