todos2/.claude/skills/infrastructure-setup.md

인프라 구축 가이드 (Infrastructure Setup)

인프라 설정 패턴입니다.

MAAS (Metal as a Service)

개요

• 베어메탈 서버 프로비저닝 도구
• Ubuntu 기반 자동 배포
• 네트워크 자동 설정

기본 설정

# MAAS 설정 예시
machines:
  - hostname: k8s-master-01
    architecture: amd64
    cpu_count: 8
    memory: 32768
    storage: 500GB
    tags:
      - kubernetes
      - master

  - hostname: k8s-worker-01
    architecture: amd64
    cpu_count: 16
    memory: 65536
    storage: 1TB
    tags:
      - kubernetes
      - worker

네트워크 설정

# 서브넷 설정
subnets:
  - cidr: 10.10.0.0/16
    gateway_ip: 10.10.0.1
    dns_servers:
      - 8.8.8.8
      - 8.8.4.4

Kubernetes 클러스터

클러스터 구성

# 마스터 노드: 3대 (HA 구성)
# 워커 노드: 3대 이상
# etcd: 마스터 노드에 내장

kubeadm 초기화

# 마스터 노드 초기화
kubeadm init --pod-network-cidr=10.244.0.0/16 \
             --control-plane-endpoint="k8s-api.example.com:6443" \
             --upload-certs

# 워커 노드 조인
kubeadm join k8s-api.example.com:6443 \
    --token <token> \
    --discovery-token-ca-cert-hash sha256:<hash>

CNI 설치 (Flannel)

kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

Rancher 설치

Docker 기반 설치

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -v /opt/rancher:/var/lib/rancher \
  rancher/rancher:latest

Helm 기반 설치

# Rancher Helm 레포 추가
helm repo add rancher-latest https://releases.rancher.com/server-charts/latest
helm repo update

# 네임스페이스 생성
kubectl create namespace cattle-system

# cert-manager 설치 (Let's Encrypt 사용 시)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Rancher 설치
helm install rancher rancher-latest/rancher \
  --namespace cattle-system \
  --set hostname=rancher.example.com \
  --set replicas=3 \
  --set ingress.tls.source=letsEncrypt \
  --set letsEncrypt.email=admin@example.com

Docker Compose 배포

docker-compose.yml 구조

services:
  # ===================
  # Infrastructure
  # ===================
  mongodb:
    image: mongo:7.0
    container_name: {프로젝트}-mongodb
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGO_USER:-admin}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD:-password123}
    ports:
      - "{호스트포트}:27017"
    volumes:
      - {프로젝트}_mongodb_data:/data/db
    networks:
      - {프로젝트}-network
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    container_name: {프로젝트}-redis
    restart: unless-stopped
    ports:
      - "{호스트포트}:6379"
    volumes:
      - {프로젝트}_redis_data:/data
    networks:
      - {프로젝트}-network

volumes:
  {프로젝트}_mongodb_data:
  {프로젝트}_redis_data:

networks:
  {프로젝트}-network:
    driver: bridge

배포 명령어

# 전체 서비스 시작
docker-compose up -d

# 특정 서비스만 재빌드
docker-compose up -d --build {서비스명}

# 로그 확인
docker-compose logs -f {서비스명}

# 서비스 상태 확인
docker-compose ps

환경 변수 관리

.env 파일

# Infrastructure
MONGO_USER=admin
MONGO_PASSWORD={비밀번호}
REDIS_URL=redis://redis:6379

# API Keys
CLAUDE_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
JWT_SECRET_KEY={시크릿키}

# Database
DB_NAME={데이터베이스명}
TARGET_COLLECTION={컬렉션명}

환경별 설정

# 개발 환경
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# 프로덕션 환경
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

백업 전략

MongoDB 백업

# 백업
BACKUP_NAME="mongodb_backup_$(date +%Y%m%d_%H%M%S)"
docker exec {프로젝트}-mongodb mongodump \
    --uri="mongodb://{user}:{password}@localhost:27017" \
    --authenticationDatabase=admin \
    --out="/tmp/$BACKUP_NAME"
docker cp {프로젝트}-mongodb:/tmp/$BACKUP_NAME ./backups/

# 복원
docker cp ./backups/$BACKUP_NAME {프로젝트}-mongodb:/tmp/
docker exec {프로젝트}-mongodb mongorestore \
    --uri="mongodb://{user}:{password}@localhost:27017" \
    --authenticationDatabase=admin \
    "/tmp/$BACKUP_NAME"

볼륨 백업

# 볼륨 백업
docker run --rm \
    -v {프로젝트}_mongodb_data:/data \
    -v $(pwd)/backups:/backup \
    alpine tar czf /backup/mongodb_volume.tar.gz -C /data .

네트워크 구성

포트 매핑 규칙

# Infrastructure (기본 포트 + 오프셋)
MongoDB: {오프셋}+27017:27017
Redis: {오프셋}+6379:6379

# Application Services
api-service: 8000:8000
admin-frontend: 3000:3000

내부 통신

# 컨테이너 간 통신은 서비스명 사용
mongodb: mongodb://{user}:{password}@mongodb:27017/
redis: redis://redis:6379

모니터링 접근점

헬스체크 엔드포인트

# MongoDB
docker exec {프로젝트}-mongodb mongosh --eval "db.adminCommand('ping')"

# Redis
docker exec {프로젝트}-redis redis-cli ping

# FastAPI 서비스
curl http://localhost:{포트}/health

로그 수집

# 전체 로그
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f {서비스명}

# 최근 100줄만
docker-compose logs --tail=100 {서비스명}