MinIO 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /minio 디렉터리 구조를 기반으로 MinIO Distributed 모드 클러스터를 Kubernetes에 설치하는 전체 과정을 안내합니다. MinIO는 고성능 오브젝트 스토리지로, S3 호환 API를 제공하며, 분산 배포를 통해 고가용성과 확장성을 지원합니다. Kustomize, Helm, Makefile을 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

  • Kubernetes 클러스터: v1.30 이상
  • 로컬 도구
    • kubectl: Kubernetes 클러스터 제어
    • kustomize: v4.x 이상
    • helm: v3.x 이상
  • 인증서: cert-manager를 통한 TLS 인증서 발급 및 네임스페이스 간 복제 구성 준비
  • DNS 등록: minio.cnapcloud.com

3. 디렉터리 구조 및 역할

minio/
├── Makefile                           # 배포 자동화 스크립트
├── kustomize/
│   ├── base/                          # 공통 리소스(Helm 차트, CRD 등)
│   └── overlays/
│       └── dev/                       # dev 환경 설정
│           ├── kustomization.yaml     # Kustomize 구성
│           └── helm/
│               ├── values.yaml        # MinIO 설정
│               └── helm-chart.yaml    # HelmChartInflationGenerator
  • Makefile: apply, delete, preview 등 배포 자동화 명령어
  • kustomize/base/: 모든 환경에 공통 적용될 리소스(Helm 차트, CRD 등)
  • kustomize/overlays/dev/: dev 환경 특화 설정
  • helm/values.yaml: MinIO Helm Chart 커스터마이징 설정

4. 설치 단계

4.1. values.yaml 커스터마이징

kustomize/overlays/dev/helm/values.yaml 파일을 열어 주요 설정을 수정합니다.

4.1.1. 클러스터/스토리지 설정

mode: distributed
replicas: 4
drivesPerNode: 1
pools: 1

persistence:
  enabled: true
  size: 5Gi

4.1.2. 리소스 제한 및 보안

resources:
  requests:
    memory: 1Gi

securityContext:
  enabled: true
  runAsUser: 1000
  runAsGroup: 1000
  fsGroup: 1000

4.1.3. 서비스 및 Ingress

service:
  type: ClusterIP
  port: "9000"

consoleService:
  type: ClusterIP
  port: "9001"

consoleIngress:
  enabled: true
  hosts:
    - minio.cnapcloud.com
  tls:
    - secretName: cnapcloud.com-tls

4.1.4. 인증 및 Secret

  • existingSecret: minio-root-secret (rootUser, rootPassword 별도 관리)

4.2. Kustomize 구성

4.2.1. kustomization.yaml 구성

kustomize/overlays/dev/kustomization.yaml에서 namespace, generators 지정

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: storage
generators:
  - ./helm/helm-chart.yaml

4.2.2. HelmChartInflationGenerator 설정

helm/helm-chart.yaml에서 Helm 차트 경로와 values 파일 지정

apiVersion: builtin
kind: HelmChartInflationGenerator
metadata:
  name: minio
name: minio
chartHome: ../../base/helm
chart: minio
releaseName: minio
valuesFile: ./helm/values.yaml
includeCRDs: true
namespace: storage

4.3. 배포 프로세스 (Makefile 활용)

Step 1: Namespace 생성

make namespace DEPLOY_ENV=dev

Step 2: 배포 미리보기

make preview DEPLOY_ENV=dev

Step 3: 배포 실행

make apply DEPLOY_ENV=dev

Step 4: 배포 상태 확인

kubectl get pods -n storage -w

5. 설치 후 검증

5.1. 리소스 상태 확인

kubectl get pods,svc,pvc,ingress -n storage

확인 사항:

  • 모든 Pod이 Running 상태 (minio-0, minio-1, minio-2, minio-3)
  • PVC가 Bound 상태 (각 Pod당 5Gi)
  • Service 생성 확인 (minio, minio-console)
  • Ingress 생성 확인 (minio.cnapcloud.com)

5.2. MinIO 클러스터 상태 확인

MinIO 클러스터의 상태와 노드 구성을 확인합니다.

5.2.1. 클러스터 정보 확인

MinIO Pod에 접속하여 먼저 mc alias를 설정한 후 클러스터 정보를 확인합니다. 여기서 admin은 MinIO의 rootUser, password는 rootPassword로, values.yaml의 existingSecret에서 참조하는 Secret의 값입니다.

kubectl -n storage exec -it minio-0 -- mc alias set minio http://localhost:9000 admin password
kubectl -n storage exec -it minio-0 -- mc admin info minio/

예상 결과:

●  minio.cnapcloud.com:9000
   Uptime: 2 minutes 
   Version: 2024-12-18T13-15-44Z
   Network: 4/4 OK 
   Drives: 4/4 OK 
   Pool: 1

Pools:
   Pool 1: 4 drives online, 0 drives offline

●  minio.cnapcloud.com:9000
   Uptime: 2 minutes 
   Version: 2024-12-18T13-15-44Z
   Network: 4/4 OK 
   Drives: 4/4 OK 
   Pool: 1

...

확인 사항:

  • 모든 노드가 online 상태
  • Network: 4/4 OK (4개 노드 모두 연결)
  • Drives: 4/4 OK (모든 드라이브 정상)

5.2.2. MinIO Console 접근 확인

kubectl -n storage get ingress

설명: Ingress를 통해 MinIO Console에 접근 가능한지 확인합니다.

확인 사항:

  • Ingress가 정상 생성되고 호스트가 minio.cnapcloud.com으로 설정
  • TLS 인증서가 적용되었는지 확인

5.2.3. S3 API 연결 테스트

kubectl -n storage exec -it minio-0 -- mc ls minio/

설명: MinIO 클라이언트를 사용하여 기본 버킷 목록을 확인합니다.

예상 결과:

[empty]

확인 사항:

  • mc 명령어가 정상 실행 (연결 성공)
  • 기본 버킷이 없거나 정상 표시

5.3. 버킷 생성 및 테스트

kubectl -n storage exec -it minio-0 -- mc mb minio/test-bucket
kubectl -n storage exec -it minio-0 -- mc ls minio/

설명: 테스트 버킷을 생성하여 MinIO의 기본 기능을 검증합니다.

예상 결과:

Bucket created successfully `minio/test-bucket`.
test-bucket/

6. 운영 및 Troubleshooting

6.1. Pod가 Running 상태가 아닌 경우

kubectl get pods -n storage
kubectl describe pod <pod명> -n storage
kubectl logs <pod명> -n storage

주요 원인:

  • PVC 미바인딩 → StorageClass 확인
  • 리소스 부족 → kubectl top nodes로 노드 상태 확인
  • 이미지 Pull 오류 → values.yaml의 image.repository, image.tag 확인

6.2. MinIO 연결 오류

  • Console 접근: Ingress URL 확인 (https://minio.cnapcloud.com)
  • API 연결: mc config host add minio https://minio.cnapcloud.com ACCESS_KEY SECRET_KEY
  • 로그 확인: kubectl logs -f minio-0 -n storage

6.3. 스토리지 용량 부족

kubectl -n storage exec -it minio-0 -- df -h /export

해결: PVC 크기 증가 또는 추가 노드 확장

6.4. Secret 관리

민감 정보(rootUser, rootPassword)는 별도 Secret으로 관리하고 values.yaml에서 existingSecret으로 참조하도록 권장합니다.

kubectl create secret generic minio-root-secret --from-literal=rootUser='admin' --from-literal=rootPassword='your-strong-password' -n storage

6.5. Network Policy

MinIO Pod 간 네트워크 통신을 제한하는 NetworkPolicy 적용을 권장합니다.

7. 보안 및 운영 권장사항

7.1. Secret 관리

민감 정보(rootUser, rootPassword)는 별도 Secret으로 관리하고 values.yaml에서 existingSecret으로 참조하도록 권장합니다.

kubectl create secret generic minio-root-secret --from-literal=rootUser='admin' --from-literal=rootPassword='your-strong-password' -n storage

7.2. Network Policy

MinIO Pod 간 네트워크 통신을 제한하는 NetworkPolicy 적용을 권장합니다.

8. 배포 제거

8.1. MinIO 삭제

make delete DEPLOY_ENV=dev

8.2. Namespace 삭제 (선택사항)

kubectl delete namespace storage

주의: Namespace를 삭제하면 PVC를 포함한 모든 데이터가 영구 삭제됩니다.

9. 부록: 최종 체크리스트

설치 전:

  • Kubernetes 클러스터 준비 (v1.20+)
  • kubectl, kustomize, helm 설치
  • 네임스페이스(storage) 생성

설치:

  • values.yaml 커스터마이징 완료
  • kustomization.yaml 구성 완료
  • make namespace 실행
  • make preview 실행 및 확인
  • make apply 실행

검증:

  • 모든 Pod이 Running 상태
  • PVC가 Bound 상태
  • Service/Ingress 생성 확인
  • MinIO Console 접근 확인
  • mc 명령어로 클러스터 상태 확인

운영:

  • Secret 관리 적용
  • Network Policy 구성
  • 모니터링 및 알림 설정 /home/ubuntu/devel/github/gitops/minio/install_guide.md
💬 무료 컨설팅 신청