☸️ Kubernetes 심화/실무 완전 가이드

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 2
  maxReplicas: 20
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60        # CPU 60% 초과 시 스케일 아웃
  - type: Resource
    resource:
      name: memory
      target:
        type: AverageValue
        averageValue: 400Mi
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300 # 5분 관찰 후 축소 — 스케일 플래핑 방지
      policies:
      - type: Pods
        value: 1
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0
      policies:
      - type: Percent
        value: 100
        periodSeconds: 15

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: myapp-vpa
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  updatePolicy:
    updateMode: "Off"   # 추천값만 계산, 실제 적용은 수동 — 운영 안전
  resourcePolicy:
    containerPolicies:
    - containerName: '*'
      minAllowed: { cpu: 50m, memory: 64Mi }
      maxAllowed: { cpu: 2, memory: 4Gi }

# 팀별 RBAC — 개발팀은 production namespace 읽기만 허용
apiVersion: v1
kind: ServiceAccount
metadata:
  name: dev-team-reader
  namespace: production
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: read-only
  namespace: production
rules:
- apiGroups: [""]
  resources: ["pods", "services", "endpoints", "configmaps"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "replicasets", "statefulsets"]
  verbs: ["get", "list", "watch"]
- apiGroups: [""]
  resources: ["pods/log"]
  verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: dev-team-binding
  namespace: production
subjects:
- kind: ServiceAccount
  name: dev-team-reader
  namespace: production
roleRef:
  kind: Role
  name: read-only
  apiGroup: rbac.authorization.k8s.io

# 운영팀 ClusterRole — 전체 네임스페이스 관리 권한
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ops-admin
rules:
- apiGroups: ["*"]
  resources: ["*"]
  verbs: ["*"]
- nonResourceURLs: ["*"]
  verbs: ["*"]
---
# CI/CD 시스템 전용 ServiceAccount (Deployment만 업데이트)
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: cicd-deployer
rules:
- apiGroups: ["apps"]
  resources: ["deployments", "statefulsets"]
  verbs: ["get", "list", "patch", "update"]
- apiGroups: [""]
  resources: ["services", "configmaps"]
  verbs: ["get", "list", "create", "update", "patch"]
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: cicd-deployer
  namespace: production
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cicd-deployer-binding
subjects:
- kind: ServiceAccount
  name: cicd-deployer
  namespace: production
roleRef:
  kind: ClusterRole
  name: cicd-deployer
  apiGroup: rbac.authorization.k8s.io

# 1. Headless Service — Pod별 안정적 DNS (postgres-0.postgres-svc, postgres-1.postgres-svc)
apiVersion: v1
kind: Service
metadata:
  name: postgres-svc
  labels:
    app: postgres
spec:
  clusterIP: None          # Headless: Pod IP를 직접 DNS에 등록
  selector:
    app: postgres
  ports:
  - port: 5432
    name: postgres
---
# 2. StatefulSet
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres-svc   # Headless Service 이름과 일치
  replicas: 3
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:16-alpine
        ports:
        - containerPort: 5432
        env:
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: postgres-secret
              key: password
        - name: PGDATA
          value: /var/lib/postgresql/data/pgdata
        resources:
          requests: { cpu: 250m, memory: 512Mi }
          limits:   { cpu: 1,    memory: 2Gi   }
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
        readinessProbe:
          exec:
            command: ["pg_isready", "-U", "postgres"]
          initialDelaySeconds: 5
          periodSeconds: 10
        livenessProbe:
          exec:
            command: ["pg_isready", "-U", "postgres"]
          initialDelaySeconds: 30
          periodSeconds: 20
  # 3. volumeClaimTemplates — Pod마다 독립 PVC 자동 생성
  volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: standard
      resources:
        requests:
          storage: 10Gi

# PodDisruptionBudget — 노드 드레인 등 자발적 중단 시 최소 2개 유지
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: postgres-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: postgres

# Kafka StatefulSet 예시 — Broker별 고유 ID, 독립 스토리지
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: kafka
spec:
  serviceName: kafka-svc
  replicas: 3
  selector:
    matchLabels:
      app: kafka
  template:
    metadata:
      labels:
        app: kafka
    spec:
      containers:
      - name: kafka
        image: bitnami/kafka:3.7
        env:
        - name: KAFKA_BROKER_ID            # Pod 순번으로 Broker ID 결정
          valueFrom:
            fieldRef:
              fieldPath: metadata.annotations['statefulset.kubernetes.io/pod-name']
        - name: KAFKA_ADVERTISED_LISTENERS
          value: "PLAINTEXT://$(POD_NAME).kafka-svc:9092"
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        volumeMounts:
        - name: kafka-data
          mountPath: /bitnami/kafka
  volumeClaimTemplates:
  - metadata:
      name: kafka-data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 20Gi

# 2. StorageClass — SSD 기반 동적 프로비저닝
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/gce-pd   # GKE: gce-pd | EKS: ebs.csi.aws.com | NCP: nks-block-storage
parameters:
  type: pd-ssd
  replication-type: regional-pd
reclaimPolicy: Retain               # Pod/PVC 삭제 후에도 디스크 유지
allowVolumeExpansion: true          # 온라인 볼륨 확장 허용
volumeBindingMode: WaitForFirstConsumer

# Redis Sentinel — HA 구성 (Primary 1 + Replica 2)
# Headless Service
apiVersion: v1
kind: Service
metadata:
  name: redis-svc
  namespace: cache
spec:
  clusterIP: None
  selector:
    app: redis
  ports:
  - port: 6379
    name: redis
  - port: 26379
    name: sentinel
---
# Client용 ClusterIP Service (Primary만 연결)
apiVersion: v1
kind: Service
metadata:
  name: redis-primary
  namespace: cache
spec:
  selector:
    app: redis
    role: primary
  ports:
  - port: 6379
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: redis
  namespace: cache
spec:
  serviceName: redis-svc
  replicas: 3
  selector:
    matchLabels:
      app: redis
  template:
    metadata:
      labels:
        app: redis
    spec:
      initContainers:
      - name: init-redis
        image: redis:7-alpine
        command:
        - bash
        - -c
        - |
          # pod-0이면 Primary, 나머지는 Replica 설정
          [[ $(hostname) == *-0 ]] && ROLE=primary || ROLE=replica
          if [[ $ROLE == primary ]]; then
            cp /mnt/config/redis-primary.conf /etc/redis/redis.conf
          else
            # primary 호스트명 주입
            sed "s/PRIMARY_HOST/redis-0.redis-svc/" \
              /mnt/config/redis-replica.conf > /etc/redis/redis.conf
          fi
        volumeMounts:
        - name: config-template
          mountPath: /mnt/config
        - name: redis-config
          mountPath: /etc/redis
      containers:
      - name: redis
        image: redis:7-alpine
        command: ["redis-server", "/etc/redis/redis.conf"]
        ports:
        - containerPort: 6379
        resources:
          requests: { cpu: 100m, memory: 256Mi }
          limits:   { cpu: 500m, memory: 1Gi }
        volumeMounts:
        - name: redis-data
          mountPath: /data
        - name: redis-config
          mountPath: /etc/redis
        readinessProbe:
          exec:
            command: ["redis-cli", "ping"]
          initialDelaySeconds: 5
          periodSeconds: 5
      - name: sentinel
        image: redis:7-alpine
        command: ["redis-sentinel", "/etc/sentinel/sentinel.conf"]
        ports:
        - containerPort: 26379
        volumeMounts:
        - name: sentinel-config
          mountPath: /etc/sentinel
      volumes:
      - name: config-template
        configMap:
          name: redis-config
      - name: redis-config
        emptyDir: {}
      - name: sentinel-config
        configMap:
          name: sentinel-config
  volumeClaimTemplates:
  - metadata:
      name: redis-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 5Gi

# MySQL Primary-Replica — initContainer로 역할 자동 분기
apiVersion: v1
kind: Service
metadata:
  name: mysql-svc
  namespace: database
spec:
  clusterIP: None
  selector:
    app: mysql
  ports:
  - port: 3306
---
apiVersion: v1
kind: Service
metadata:
  name: mysql-read
  namespace: database
spec:
  selector:
    app: mysql
  ports:
  - port: 3306
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
  namespace: database
spec:
  serviceName: mysql-svc
  replicas: 3
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      initContainers:
      - name: init-mysql
        image: mysql:8.4
        command:
        - bash
        - -c
        - |
          # Pod 순번으로 server-id 결정, pod-0은 Primary
          ORDINAL=$(hostname | awk -F- '{print $NF}')
          echo [mysqld] > /mnt/conf.d/server-id.cnf
          echo server-id=$((100 + $ORDINAL)) >> /mnt/conf.d/server-id.cnf
          if [[ $ORDINAL -eq 0 ]]; then
            cp /mnt/config/primary.cnf /mnt/conf.d/
          else
            cp /mnt/config/replica.cnf /mnt/conf.d/
          fi
        volumeMounts:
        - name: conf
          mountPath: /mnt/conf.d
        - name: config-map
          mountPath: /mnt/config
      - name: clone-mysql
        image: gcr.io/google-samples/xtrabackup:1.0
        command:
        - bash
        - -c
        - |
          # pod-0이 아닌 경우 이전 Pod에서 데이터 복제
          ORDINAL=$(hostname | awk -F- '{print $NF}')
          [[ $ORDINAL -eq 0 ]] && exit 0
          PEER=mysql-$(($ORDINAL - 1)).mysql-svc
          ncat --recv-only $PEER 3307 | xbstream -x -C /var/lib/mysql
          xtrabackup --prepare --target-dir=/var/lib/mysql
        volumeMounts:
        - name: data
          mountPath: /var/lib/mysql
          subPath: mysql
        - name: conf
          mountPath: /etc/mysql/conf.d
      containers:
      - name: mysql
        image: mysql:8.4
        env:
        - name: MYSQL_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: ROOT_PASSWORD
        ports:
        - containerPort: 3306
        resources:
          requests: { cpu: 500m, memory: 1Gi }
          limits:   { cpu: 2,    memory: 4Gi }
        volumeMounts:
        - name: data
          mountPath: /var/lib/mysql
          subPath: mysql
        - name: conf
          mountPath: /etc/mysql/conf.d
        readinessProbe:
          exec:
            command: ["mysqladmin", "ping", "-uroot", "-p$(MYSQL_ROOT_PASSWORD)"]
          initialDelaySeconds: 30
          periodSeconds: 10
      - name: xtrabackup
        image: gcr.io/google-samples/xtrabackup:1.0
        ports:
        - containerPort: 3307
        command:
        - bash
        - -c
        - |
          # Replica 클론 요청 대기 (ncat 서버)
          cd /var/lib/mysql
          if [[ -f xtrabackup_slave_info && "x$(<xtrabackup_slave_info)" != "x" ]]; then
            cat xtrabackup_slave_info | sed -E 's/;*s*$//; s/MASTER/SOURCE/' \
              | mysql -uroot -p${MYSQL_ROOT_PASSWORD}
            rm -f xtrabackup_slave_info xtrabackup_binlog_info
          fi
          exec ncat --listen --keep-open --send-only --max-conns=1 3307 -c \
            "xtrabackup --backup --slave-info --stream=xbstream --host=127.0.0.1 --user=root --password=${MYSQL_ROOT_PASSWORD}"
        volumeMounts:
        - name: data
          mountPath: /var/lib/mysql
          subPath: mysql
        - name: conf
          mountPath: /etc/mysql/conf.d
      volumes:
      - name: conf
        emptyDir: {}
      - name: config-map
        configMap:
          name: mysql-config
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 20Gi

# Elasticsearch StatefulSet — 3노드 클러스터
apiVersion: v1
kind: Service
metadata:
  name: es-svc
  namespace: search
spec:
  clusterIP: None
  selector:
    app: elasticsearch
  ports:
  - port: 9200
    name: http
  - port: 9300
    name: transport
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: elasticsearch
  namespace: search
spec:
  serviceName: es-svc
  replicas: 3
  selector:
    matchLabels:
      app: elasticsearch
  template:
    metadata:
      labels:
        app: elasticsearch
    spec:
      initContainers:
      - name: fix-permissions
        image: busybox
        command: ["sh", "-c", "chown -R 1000:1000 /usr/share/elasticsearch/data"]
        securityContext:
          privileged: true
        volumeMounts:
        - name: es-data
          mountPath: /usr/share/elasticsearch/data
      - name: increase-vm-max-map
        image: busybox
        command: ["sysctl", "-w", "vm.max_map_count=262144"]
        securityContext:
          privileged: true
      containers:
      - name: elasticsearch
        image: docker.elastic.co/elasticsearch/elasticsearch:8.13.0
        env:
        - name: cluster.name
          value: "k8s-es-cluster"
        - name: node.name
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: discovery.seed_hosts
          value: "elasticsearch-0.es-svc,elasticsearch-1.es-svc,elasticsearch-2.es-svc"
        - name: cluster.initial_master_nodes
          value: "elasticsearch-0,elasticsearch-1,elasticsearch-2"
        - name: ES_JAVA_OPTS
          value: "-Xms2g -Xmx2g"
        - name: xpack.security.enabled
          value: "true"
        - name: ELASTIC_PASSWORD
          valueFrom:
            secretKeyRef:
              name: es-secret
              key: password
        ports:
        - containerPort: 9200
          name: http
        - containerPort: 9300
          name: transport
        resources:
          requests: { cpu: 500m, memory: 3Gi }
          limits:   { cpu: 2,    memory: 5Gi }
        volumeMounts:
        - name: es-data
          mountPath: /usr/share/elasticsearch/data
        readinessProbe:
          httpGet:
            path: /_cluster/health?local=true
            port: 9200
            httpHeaders:
            - name: Authorization
              value: "Basic ZWxhc3RpYzpjaGFuZ2VtZQ=="
          initialDelaySeconds: 30
          periodSeconds: 10
  volumeClaimTemplates:
  - metadata:
      name: es-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 30Gi

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: elasticsearch
spec:
  serviceName: elasticsearch-svc
  replicas: 5
  podManagementPolicy: Parallel   # 5개 Pod을 동시에 기동 — 순서 대기 없이 스케일 속도 향상
  selector:
    matchLabels: { app: elasticsearch }
  template:
    metadata:
      labels: { app: elasticsearch }
    spec:
      containers:
      - name: elasticsearch
        image: elasticsearch:8.13.0
        env:
        - name: discovery.seed_hosts
          value: "elasticsearch-0.elasticsearch-svc,elasticsearch-1.elasticsearch-svc"
        - name: cluster.initial_master_nodes
          value: "elasticsearch-0,elasticsearch-1,elasticsearch-2"
        volumeMounts:
        - name: es-data
          mountPath: /usr/share/elasticsearch/data
  volumeClaimTemplates:
  - metadata: { name: es-data }
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources: { requests: { storage: 100Gi } }

# ── VolumeSnapshot 기반 백업 & 복구 (CSI 드라이버 + VolumeSnapshotClass 필요) ──
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshotClass
metadata:
  name: csi-snapclass
driver: ebs.csi.aws.com          # GKE: pd.csi.storage.gke.io | NCP: nks-block-storage
deletionPolicy: Retain            # 원본 PVC 삭제되어도 스냅샷 유지
---
# 1. 스냅샷 생성 — 배포 전 / 대규모 마이그레이션 전 백업
apiVersion: snapshot.storage.k8s.io/v1
kind: VolumeSnapshot
metadata:
  name: postgres-snap-before-upgrade
  namespace: database
spec:
  volumeSnapshotClassName: csi-snapclass
  source:
    persistentVolumeClaimName: postgres-data-postgres-0
---
# 2. 스냅샷으로부터 새 PVC 복구 — 장애 발생 시 별도 이름으로 복원해 데이터 검증 후 교체
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data-restored
  namespace: database
spec:
  storageClassName: fast-ssd
  dataSource:
    name: postgres-snap-before-upgrade
    kind: VolumeSnapshot
    apiGroup: snapshot.storage.k8s.io
  accessModes: ["ReadWriteOnce"]
  resources:
    requests:
      storage: 50Gi

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: fluent-bit
  namespace: logging
spec:
  selector:
    matchLabels: { app: fluent-bit }
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1        # 한 번에 노드 1개씩만 재시작 — 로그 유실 구간 최소화
  template:
    metadata:
      labels: { app: fluent-bit }
    spec:
      tolerations:              # control-plane 노드에도 배포해 마스터 로그까지 수집
      - key: node-role.kubernetes.io/control-plane
        effect: NoSchedule
      serviceAccountName: fluent-bit
      containers:
      - name: fluent-bit
        image: fluent/fluent-bit:3.0
        resources:
          requests: { cpu: 100m, memory: 128Mi }   # 노드 수만큼 곱해지므로 최소로 유지
          limits:   { cpu: 300m, memory: 256Mi }
        volumeMounts:
        - name: varlog
          mountPath: /var/log            # 노드의 로그 디렉터리를 직접 마운트
          readOnly: true
        - name: dockercontainers
          mountPath: /var/lib/docker/containers
          readOnly: true
      volumes:
      - name: varlog
        hostPath: { path: /var/log }
      - name: dockercontainers
        hostPath: { path: /var/lib/docker/containers }

apiVersion: batch/v1
kind: Job
metadata:
  name: db-migration-v2
  namespace: production
spec:
  backoffLimit: 3                 # 3회 실패하면 포기 (무한 재시도 방지)
  activeDeadlineSeconds: 600       # 10분 넘으면 강제 종료
  ttlSecondsAfterFinished: 3600    # 완료 1시간 후 자동 정리
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: myapp-migrator:2.1.0
        command: ["./migrate.sh", "--target=v2"]
        resources:
          requests: { cpu: 200m, memory: 256Mi }
          limits:   { cpu: 500m, memory: 512Mi }
        envFrom:
        - secretRef: { name: db-credentials }

apiVersion: batch/v1
kind: CronJob
metadata:
  name: postgres-nightly-backup
  namespace: database
spec:
  schedule: "0 3 * * *"            # 매일 새벽 3시 (클러스터 kube-controller-manager 시간대 기준)
  timeZone: "Asia/Seoul"           # K8s 1.27+ — CronJob 자체에 타임존 지정 가능
  concurrencyPolicy: Forbid        # 이전 백업이 아직 실행 중이면 이번 회차는 건너뜀
  startingDeadlineSeconds: 300     # 5분 안에 시작 못하면 이번 회차는 포기
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 5        # 실패 이력은 조금 더 오래 남겨 원인 분석
  jobTemplate:
    spec:
      backoffLimit: 2
      activeDeadlineSeconds: 1800
      template:
        spec:
          restartPolicy: OnFailure
          containers:
          - name: backup
            image: postgres:16-alpine
            command:
            - sh
            - -c
            - |
              pg_dump -h postgres-svc -U postgres mydb | \
              gzip > /backup/mydb-$(date +%Y%m%d).sql.gz
            volumeMounts:
            - name: backup-storage
              mountPath: /backup
          volumes:
          - name: backup-storage
            persistentVolumeClaim: { claimName: backup-pvc }

# ── Multi-stage build — Spring Boot AI Agent ──────────────────
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /app
COPY gradlew build.gradle.kts settings.gradle.kts ./
COPY gradle ./gradle
RUN ./gradlew dependencies --no-daemon -q

COPY src ./src
RUN ./gradlew bootJar --no-daemon -q

# ── Runtime image ─────────────────────────────────────────────
FROM eclipse-temurin:21-jre-alpine
WORKDIR /app

# 데이터 · 로그 디렉터리 생성 (PVC 마운트 포인트)
RUN mkdir -p /app/data /app/logs && \
    addgroup -S agent && adduser -S agent -G agent && \
    chown -R agent:agent /app

COPY --from=builder /app/build/libs/*.jar agent.jar
USER agent

# PVC 볼륨 선언 (K8s가 마운트)
VOLUME ["/app/data", "/app/logs"]

EXPOSE 8080
ENTRYPOINT ["java", \
  "-XX:MaxRAMPercentage=75.0", \
  "-XX:+UseG1GC", \
  "-Dspring.profiles.active=prod", \
  "-Dlogging.file.path=/app/logs", \
  "-jar", "agent.jar"]

apiVersion: v1
kind: ConfigMap
metadata:
  name: java-agent-config
  namespace: ai-agent
data:
  application-prod.yml: |
    spring:
      datasource:
        url: jdbc:h2:file:/app/data/agentdb;AUTO_SERVER=TRUE
        driver-class-name: org.h2.Driver
        username: agent
      jpa:
        hibernate:
          ddl-auto: update
        show-sql: false
      ai:
        openai:
          base-url: http://llm-gateway-svc:8080   # 내부 LLM Gateway
          api-key: ${OPENAI_API_KEY}

    agent:
      vector-store:
        path: /app/data/faiss-index          # FAISS 로컬 인덱스
        dimension: 1536
      memory:
        persist-path: /app/data/memory.db   # Agent 메모리 저장
        max-tokens: 4096

    logging:
      file:
        name: /app/logs/agent.log
        max-size: 100MB
        max-history: 90                       # 90일 보관
      pattern:
        file: "%d{yyyy-MM-dd HH:mm:ss} [%X{traceId}] %-5level %logger{36} - %msg%n"

    management:
      endpoints:
        web:
          exposure:
            include: health,metrics,prometheus
      metrics:
        export:
          prometheus:
            enabled: true

# ── Headless Service (Pod 간 DNS) ────────────────────────────
apiVersion: v1
kind: Service
metadata:
  name: java-agent-svc
  namespace: ai-agent
spec:
  clusterIP: None
  selector:
    app: java-agent
  ports:
  - port: 8080
    name: http
---
# ── ClusterIP Service (내부 API 호출용) ──────────────────────
apiVersion: v1
kind: Service
metadata:
  name: java-agent-api
  namespace: ai-agent
spec:
  selector:
    app: java-agent
  ports:
  - port: 80
    targetPort: 8080
    name: http
---
# ── StatefulSet ───────────────────────────────────────────────
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: java-agent
  namespace: ai-agent
spec:
  serviceName: java-agent-svc       # Headless Service 이름
  replicas: 2
  selector:
    matchLabels:
      app: java-agent
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 0                  # 전체 롤링 업데이트
  template:
    metadata:
      labels:
        app: java-agent
    spec:
      terminationGracePeriodSeconds: 60
      imagePullSecrets:
      - name: regcred
      initContainers:
      # data 디렉터리 권한 초기화 (PVC 마운트 시 root 소유 문제 방지)
      - name: init-permissions
        image: busybox:1.36
        command: ["sh", "-c", "chown -R 1000:1000 /app/data /app/logs"]
        volumeMounts:
        - name: agent-state
          mountPath: /app/data
        - name: agent-logs
          mountPath: /app/logs
      containers:
      - name: java-agent
        image: registry.aidevops.kr/java-agent:1.0.0
        ports:
        - containerPort: 8080
          name: http
        env:
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: java-agent-secret
              key: OPENAI_API_KEY
        - name: SPRING_DATASOURCE_PASSWORD
          valueFrom:
            secretKeyRef:
              name: java-agent-secret
              key: SPRING_DATASOURCE_PASSWORD
        # Pod 고유 ID를 Agent ID로 활용 (java-agent-0, java-agent-1)
        - name: AGENT_ID
          value: "$(POD_NAME)"
        envFrom:
        - configMapRef:
            name: java-agent-config   # application-prod.yml 마운트용 별도 ConfigMap
        resources:
          requests:
            cpu: 500m
            memory: 1Gi
          limits:
            cpu: 2
            memory: 3Gi
        volumeMounts:
        - name: agent-state           # PVC 1 — 에이전트 상태 · 벡터 인덱스
          mountPath: /app/data
        - name: agent-logs            # PVC 2 — 감사/운영 로그
          mountPath: /app/logs
        - name: app-config
          mountPath: /app/config
          readOnly: true
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
          failureThreshold: 3
        livenessProbe:
          httpGet:
            path: /actuator/health/liveness
            port: 8080
          initialDelaySeconds: 60
          periodSeconds: 20
          failureThreshold: 4
        lifecycle:
          preStop:
            exec:
              # Graceful shutdown — 진행 중인 Agent 작업 완료 대기
              command: ["sh", "-c", "sleep 10"]
      volumes:
      - name: app-config
        configMap:
          name: java-agent-config
  # ── PVC 2개 — volumeClaimTemplates ────────────────────────
  volumeClaimTemplates:
  - metadata:
      name: agent-state
      labels:
        app: java-agent
        volume: state
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: fast-ssd
      resources:
        requests:
          storage: 20Gi
  - metadata:
      name: agent-logs
      labels:
        app: java-agent
        volume: logs
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: nfs-client     # 로그는 NFS로 중앙화 가능
      resources:
        requests:
          storage: 10Gi

# Ingress — 외부에서 Java Agent API 접근
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: java-agent-ingress
  namespace: ai-agent
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"    # Agent 응답 대기
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  ingressClassName: nginx
  tls:
  - hosts:
    - agent-api.aidevops.kr
    secretName: agent-api-tls
  rules:
  - host: agent-api.aidevops.kr
    http:
      paths:
      - path: /api/agent
        pathType: Prefix
        backend:
          service:
            name: java-agent-api
            port:
              number: 80

# PodDisruptionBudget — 최소 1개 Pod 항상 유지
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: java-agent-pdb
  namespace: ai-agent
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: java-agent

apiVersion: apps/v1
kind: Deployment
metadata:
  name: llm-inference
  namespace: ai-agent
spec:
  replicas: 2
  selector:
    matchLabels: { app: llm-inference }
  template:
    metadata:
      labels: { app: llm-inference }
    spec:
      nodeSelector:
        gpu-type: a10g                 # GPU 종류별로 노드 풀을 분리해 라벨링
      tolerations:
      - key: nvidia.com/gpu
        operator: Equal
        value: present
        effect: NoSchedule
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args: ["--model", "/models/llama-3-8b", "--gpu-memory-utilization", "0.9"]
        resources:
          requests:
            cpu: "4"
            memory: 24Gi
            nvidia.com/gpu: "1"        # GPU는 정수 단위만 요청 가능 — 분할 불가
          limits:
            cpu: "8"
            memory: 32Gi
            nvidia.com/gpu: "1"
        volumeMounts:
        - name: model-cache
          mountPath: /models
        readinessProbe:                 # 모델 로딩(수십 초~수 분) 완료 전 트래픽 차단
          httpGet: { path: /health, port: 8000 }
          initialDelaySeconds: 60
          periodSeconds: 10
          failureThreshold: 30
        livenessProbe:
          httpGet: { path: /health, port: 8000 }
          initialDelaySeconds: 120
          periodSeconds: 30
      volumes:
      - name: model-cache
        persistentVolumeClaim:
          claimName: llm-model-pvc      # 모델 가중치는 이미지가 아닌 PVC에서 마운트

# GPU Pod 오토스케일링 — CPU가 아닌 큐 길이/동시 요청 수 기반 커스텀 메트릭 권장
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: llm-inference-hpa
  namespace: ai-agent
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: llm-inference
  minReplicas: 1               # GPU는 고가 자원 — 최소치를 낮게 유지
  maxReplicas: 6               # 클러스터 내 확보 가능한 GPU 수로 상한 설정
  metrics:
  - type: Pods
    pods:
      metric:
        name: inference_queue_length   # Prometheus Adapter로 노출한 커스텀 메트릭
      target:
        type: AverageValue
        averageValue: "5"

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: llm-inference-route
spec:
  parentRefs:
  - name: main-gateway
  rules:
  - backendRefs:
    - name: llm-inference-stable
      port: 8000
      weight: 95        # 검증된 기존 모델
    - name: llm-inference-canary
      port: 8000
      weight: 5         # 신규 모델 — 점진적으로 weight를 늘려감

# Prometheus Adapter 없이도 Redis/SQS 등 외부 큐 지표로 바로 스케일링
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: llm-inference-scaler
  namespace: ai-agent
spec:
  scaleTargetRef:
    name: llm-inference
  minReplicaCount: 1        # GPU는 고가 자원 — 유휴 상태에서는 0까지도 검토 가능
  maxReplicaCount: 6
  cooldownPeriod: 300        # 스케일 다운 전 대기 — GPU Pod는 축소·재확보 비용이 크므로 여유 있게
  triggers:
  - type: redis
    metadata:
      address: redis.ai-agent.svc:6379
      listName: inference-queue
      listLength: "5"        # 큐에 5개 이상 쌓이면 스케일 아웃

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: llm-inference-pdb
  namespace: ai-agent
spec:
  minAvailable: 1            # 노드 유지보수 중에도 최소 1개는 서비스 가능 상태 유지
  selector:
    matchLabels: { app: llm-inference }

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "llm-inference.fullname" . }}
  labels:
    {{- include "llm-inference.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "llm-inference.fullname" . }}
  template:
    metadata:
      labels:
        app: {{ include "llm-inference.fullname" . }}
    spec:
      nodeSelector:
        gpu-type: {{ .Values.gpu.nodeType }}
      containers:
      - name: vllm
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        args: ["--model", "{{ .Values.model.path }}"]
        resources:
          requests:
            nvidia.com/gpu: {{ .Values.gpu.count }}
          limits:
            nvidia.com/gpu: {{ .Values.gpu.count }}

replicaCount: 3
image:
  repository: vllm/vllm-openai
  tag: "0.6.2"
gpu:
  nodeType: a100    # 스테이징은 values-staging.yaml에서 a10g로 override
  count: 1
model:
  path: /models/llama-3-70b

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "llm-inference.fullname" . }}-migrate
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-delete-policy": hook-succeeded   # 성공한 Job은 정리, 실패 시 원인 조사를 위해 남김
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: migrate
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        command: ["python", "scripts/sync_model_registry.py"]

# GatewayClass는 contour-gateway-provisioner.yaml 적용 시 자동 생성됨
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: contour-gateway
  namespace: projectcontour
spec:
  gatewayClassName: contour
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    hostname: "*.aidevops.kr"
    allowedRoutes:
      namespaces:
        from: All
  - name: https
    protocol: HTTPS
    port: 443
    hostname: "*.aidevops.kr"
    tls:
      mode: Terminate
      certificateRefs:
      - kind: Secret
        name: wildcard-aidevops-kr-tls   # cert-manager가 DNS-01로 발급
    allowedRoutes:
      namespaces:
        from: All