autoflow-server-mgmt/deployment_guide.md

# AWS Outposts EKS 배포 가이드 (AutoFlow)

본 가이드는 AutoFlow 서버(Spring Boot), 웹 콘솔(Vue.js), 그리고 MariaDB를 AWS Outposts EKS 환경에 배포하는 절차를 설명합니다.

---

## 1. 사전 준비 사항

### 1-1. 네임스페이스 생성
모든 리소스는 `etri-aisw` 네임스페이스에 배포됩니다.
```bash
kubectl create namespace etri-aisw
```

### 1-2. ECR 로그인
이미지를 푸시하기 위해 ECR에 로그인합니다.
```bash
aws ecr get-login-password --region {REGION} | docker login --username AWS --password-stdin {AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com
```

---

## 2. Docker 이미지 빌드 및 ECR 푸시

### 2-1. 서버(Spring Boot) 이미지 빌드
```bash
cd autoflow-server-mgmt

# JAR 파일 빌드
./gradlew bootJar

# Docker 이미지 빌드
docker build -t autoflow-server:latest .

# ECR 태그 및 푸시
docker tag autoflow-server:latest {AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com/autoflow-server:latest
docker push {AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com/autoflow-server:latest
```

### 2-2. 웹 콘솔(Vue.js) 이미지 빌드
```bash
cd ../autoflow-web-console

# 정적 파일 빌드
npm install
npm run build

# Docker 이미지 빌드
docker build -t autoflow-web:latest .

# ECR 태그 및 푸시
docker tag autoflow-web:latest {AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com/autoflow-web:latest
docker push {AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com/autoflow-web:latest
```

---

## 3. 매니페스트 파일 수정

배포 전 `kubernetes-aws.yaml` 파일의 아래 항목들을 실제 환경에 맞게 수정해야 합니다.

### 2-1. 이미지 경로 수정
`spec.template.spec.containers.image` 항목을 위에서 푸시한 ECR 경로로 변경합니다.

### 2-2. ALB(Ingress) 주석 수정
Ingress 리소스의 `annotations` 섹션에서 다음 값을 수정합니다.
- `alb.ingress.kubernetes.io/subnets`: 실제 서브넷 ID들
- `alb.ingress.kubernetes.io/security-groups`: 실제 보안 그룹 ID
- `alb.ingress.kubernetes.io/customer-owned-ipv4-pool`: 실제 CoIP 풀 ID

---

## 4. 리소스 배포 절차

### 단계 1: MariaDB 초기화 SQL 배포
데이터베이스 스키마 자동 생성을 위해 ConfigMap을 먼저 배포합니다.
```bash
kubectl apply -f mariadb-init-configmap.yaml
```

### 단계 2: 통합 리소스 배포
MariaDB(PVC, Deployment, Service), Server(Deployment, Service, Ingress), Secret 등을 한 번에 배포합니다.
```bash
kubectl apply -f kubernetes-aws.yaml
```

### 단계 3: 웹 콘솔 배포 (선택 사항)
웹 콘솔 프로젝트 디렉토리로 이동하여 배포를 수행합니다.
```bash
cd ../autoflow-web-console
kubectl apply -f kubernetes-aws.yaml
```

---

## 5. 배포 확인 및 검증

### 4-1. Pod 상태 확인
모든 Pod가 `Running` 상태인지 확인합니다.
```bash
kubectl get pods -n etri-aisw
```

### 4-2. 서비스 및 인그레스 주소 확인
ALB 외장 주소(ADDRESS)가 할당되었는지 확인합니다.
```bash
kubectl get ingress -n etri-aisw
```

### 4-3. MariaDB 초기화 확인
MariaDB 로그를 통해 SQL 스크립트가 정상 실행되었는지 확인합니다.
```bash
kubectl logs -n etri-aisw -l app=mariadb
```

---

## 6. 문제 해결 (Troubleshooting)

- **Pod Pending**: `cpu` 노드 그룹의 자원이 부족하거나 `nodeSelector`가 일치하지 않는지 확인하세요.
- **ImagePullBackOff**: ECR 접근 권한(IAM Role) 또는 이미지 경로를 확인하세요.
- **503 Service Temporarily Unavailable**: ALB의 헬스체크 경로(`/autoflow-server-mgmt/actuator/health`)가 정상 응답(200 OK)을 주는지 확인하세요.
- **DB 접속 에러**: `RDS_HOSTNAME`이 `mariadb-svc`로 올바르게 설정되었는지 확인하세요.