맥미니(Mac mini) 환경 Colima + Docker + Kubernetes 서버 구성

1. 목적: macOS에서 Docker 데스크탑 없이 Colima로 컨테이너/쿠버네티스(k3s) 환경을 안정적으로 운영하고, 데이터(볼륨)를 안전하고 관리하기 쉬운 호스트 디렉토리 구조에 보관
2. 핵심 아이디어: Colima VM(리마/Lima 기반)에 호스트 디렉토리 마운트를 미리 지정하면, Docker bind mount나 Compose 볼륨을 통해 컨테이너가 호스트 파일을 읽고 쓸 수 있음. (Colima의 --mount / mounts 옵션 활용)

사전 준비

• macOS (권장: Ventura/Monterey 이상; virtiofs 사용 시 macOS 13+ 권장)
• Homebrew 설치
• 기본 도구:(Colima docs 및 명령어 참조).
• brew install colima docker docker-compose kubectl

Colima 시작 (권장 설정 — Kubernetes 포함, 호스트 디렉토리 마운트)

• 권장: macOS 13+이면 vz VM 타입 + virtiofs 마운트가 성능/호환성에서 우수합니다.

# 예시: CPU 4, 메모리 8GiB, 디스크 100GiB, k8s 활성화, host dir 마운트
mkdir -p ~/colima/{volumes,projects,backups,configs,logs}

colima start \
  --cpus 4 --memory 8 --disk 100 \
  --kubernetes \
  --vm-type vz --mount-type virtiofs \
  --mount ~/colima/volumes:w \
  --mount ~/colima/projects:w \
  --mount ~/colima/configs:w

• 설명: --mount <hostpath>:w 로 Colima VM 내부에 마운트해주면, 이후 Docker Compose의 - ./somepath:/container/path 같은 바인드 마운트가 동작합니다. (mount type은 sshfs,9p,virtiofs 중 선택 가능)

디렉토리/볼륨 구조 설계(권장)

• 목적: 데이터 유형별로 경로를 분리 → 백업·권한·보안 정책 적용 용이.

~/colima/
├─ projects/                # 소스 코드 / 애플리케이션별 디렉토리
│  ├─ app1/
│  └─ app2/
├─ volumes/                 # 컨테이너에 바인드/볼륨으로 연결되는 실제 데이터
│  ├─ postgres/             # postgres 데이터 디렉토리
│  ├─ redis/
│  ├─ registry/             # 로컬 레지스트리 데이터
│  └─ uploads/              # 사용자 업로드 등
├─ backups/                 # DB dump, tarball 등 백업 저장소
├─ configs/                 # Traefik/nginx/compose 파일 등 설정 원본
└─ logs/                    # 호스트수집용(선택)

• 설계 원칙
  • 앱별 데이터는 ~/colima/volumes/<앱명> 형태로 분리.
  • 백업(주기 덤프)은 ~/colima/backups로 모아 백업 도구(aws cli, rclone 등)로 외부 저장소 전송.
  • 설정은 Git으로 관리(암호는 제외).

Docker 볼륨 vs Bind-mount (Colima 환경에서의 권장)

• 🔸 Bind-mount: 개발/테스트에서 편리(호스트 파일 바로 반영). Colima에서는 해당 호스트 경로가 Colima VM에 마운트 되어 있어야 정상 동작합니다. (colima start --mount ~/colima/volumes:w)

300x250

• 🔸 Named volumes: Docker가 VM 내부에 관리하는 볼륨으로, 경로가 /var/lib/docker/volumes/... (또는 containerd의 경우 해당 위치)로 저장됩니다 — 호스트(macOS)에서 직접 접근하려면 VM 내부 접근(ssh)이나 docker run --rm -v 백업 방식 사용 필요. 호스트에서 직접 파일 관리/백업을 쉽게 하려면 bind-mount으로 호스트 경로를 연결하는 편이 운영에 수월합니다.

예제: Docker Compose (Postgres + App) — 호스트 바인드 마운트 방식

version: "3.8"
services:
  db:
    image: postgres:15
    restart: always
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - type: bind
        source: ~/colima/volumes/postgres
        target: /var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 30s
      timeout: 5s

  app:
    image: myorg/app:latest
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "8080:8080"
    volumes:
      - type: bind
        source: ~/colima/projects/app
        target: /app

• 주의: ~/colima/volumes/postgres는 Colima 시작 시 --mount로 마운트되어 있어야 접근·퍼미션 문제가 없습니다. (마운트가 없으면 컨테이너가 VM 내부의 빈 디렉토리를 사용하게 되어 호스트와 데이터가 분리될 수 있음)

Kubernetes (Colima의 k3s)에서 로컬 스토리지 사용

• Colima는 내부적으로 k3s를 사용해 로컬 쿠버네티스를 제공합니다. (버전은 Colima/k3s 설정에 따름) 기본적으로 local-path 같은 로컬 프로비저너가 활성화되어 있을 가능성이 큽니다. (확인: kubectl get storageclass)

간단한 hostPath PV 예시 (테스트/개발용)

주의: hostPath는 로컬 노드 파일시스템을 직접 쓰므로 프로덕션용 아님. Colima의 k3s 노드 내부 경로(예: /var/lib/colima-volumes/... 또는 Colima VM에 마운트한 경로)를 지정해야 합니다.

apiVersion: v1
kind: PersistentVolume
metadata:
  name: local-pv-postgres
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: /var/colima-data/postgres   # <-- Colima VM 내부 경로 (또는 /host/path if mounted)
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

• 권장 워크플로: 호스트(맥) 경로 → Colima 마운트 → k8s hostPath로 사용
  예: ~/colima/volumes/postgres 를 Colima에 마운트하면 VM 내부에서 /hosthome/youruser/colima/volumes/postgres 같은 경로로 보이고, 이를 PV의 hostPath로 지정하여 쿠버네티스에서 사용합니다.

권장: 로컬 스토리지 프로비저너 사용

• 개발 편의상 local-path-provisioner 같은 동적 프로비저너를 사용하면 PVC 생성 시 자동으로 노드의 디렉토리를 만들어주므로 편리합니다. k3s에는 이미 유사 기능이 포함되어 있을 수 있습니다. (확인: kubectl get storageclass)

권한(UID/GID) 문제 해결 팁

• macOS ↔ VM ↔ 컨테이너 경계에서 파일 소유권(UID/GID)이 달라져 권한문제가 발생합니다.
• 해결책
  • 컨테이너에서 사용하는 프로세스의 UID를 호스트 디렉토리의 소유자와 맞춤(예: chown -R 1000:1000 ~/colima/volumes/postgres)
  • 또는, 컨테이너 시작 시 PUID/PGID 환경변수 주입(이미지에서 지원 시)
  • 혹은 Dockerfile에서 non-root 사용자 생성 후 사용 권장. 관련 문제와 해결은 커뮤니티 문서 참조.

백업·복구(실전)

• DB dump 스케줄(예: cron on host or cron in backup container)

  # 예시: postgres dump (호스트에서 실행)
  PGPASSWORD=secret pg_dump -U app -h localhost -p 5432 appdb | gzip > ~/colima/backups/appdb_$(date +%F).sql.gz
  aws s3 cp ~/colima/backups/appdb_$(date +%F).sql.gz s3://BUCKET/path/

• 볼륨 전체 백업

  # 임시 컨테이너로 바인드된 볼륨을 tar로 백업
  docker run --rm -v ~/colima/volumes/postgres:/data -v ~/colima/backups:/backup alpine \
    sh -c "cd /data && tar czf /backup/postgres_$(date +%F).tgz ."

• 주기적 복원 테스트(분기별) 권장.

모니터링 / 로깅 / 보안 포인트

• 모니터링: Prometheus + node_exporter(macOS용 또는 Colima VM 내부 exporter) + Grafana.
• 로그: 컨테이너 로그는 ELK/Fluentd/Vector → 외부 SIEM으로 전송 권장.
• 보안
  • 민감정보는 Vault/Docker Secrets 사용(환경변수 직접 노출 금지).
  • 이미지 스캔: Trivy 등으로 CI에서 스캔 후 배포.
  • SSH는 키 기반만 허용, macOS 방화벽/PF로 외부 포트 최소화.

운영 체크리스트 (간단)

• 데일리: colima status, docker ps, kubectl get pods -A 확인
• 주간: 백업 성공 확인, 디스크 사용량 검사 (colima info/colima status 및 VM 내부 df -h)
• 월간: 이미지 취약점 스캔 결과 검토, TLS/인증서 만료 점검

자주 발생하는 문제와 해결

• 마운트 경로가 반영되지 않음 → Colima 시작 시 --mount로 해당 경로를 명시했는지 확인. (또는 colima stop && colima start --mount ...)
• 권한 문제(perm denied) → 호스트 디렉토리 소유자(UID/GID) 조정 또는 컨테이너의 사용자 맞춤.
• Docker 소켓 경로 문제 → colima status로 소켓 위치 확인 및 심볼릭 링크 필요시 생성.

참고(핵심 문서)

• Colima 공식 문서 (설치/flags/마운트 관련)
• Docker 볼륨·바인드 문서(운영 원칙)
• Kubernetes PersistentVolume 개념 문서
• Lima/마운트 동작(Colima 내부 VM의 파일시스템 마운트 참고)