Spring MSA Demo 설치 가이드

1. 개요

본 문서는 gitops 저장소의 /msa-demo 디렉터리 구조를 기반으로 MSA-Demo 애플리케이션을 Kubernetes 클러스터에 설치하는 전체 과정을 안내합니다. Spring MSA Demo는 Project API와 Orchestrator API로 구성된 마이크로서비스 데모 애플리케이션입니다. Kustomize와 Makefile을 활용한 배포 자동화, 환경별 설정, 주요 커스텀 옵션, 운영 팁을 포함합니다.

2. 사전 요구사항

  • Kubernetes 클러스터: v1.30 이상
  • 로컬 도구: kubectl, kustomize 설치 완료
  • 인증서: cert-manager를 통한 TLS 인증서 발급 및 네임스페이스 간 복제 구성 준비
  • DNS 등록: msa-demo.cnapcloud.com
  • Keycloak Client 설정: msa client 생성

3. 디렉터리 구조 및 역할

msa-demo/
├── Makefile                           # 배포 자동화 스크립트
├── kustomize/
│   ├── base/                          # 공통 리소스(Deployment, Service 등)
│   │   ├── kustomization.yaml         # Base Kustomize 구성
│   │   └── resources/                 # 리소스 파일들
│   └── overlays/
│       └── dev/                       # dev 환경 설정
│           ├── kustomization.yaml     # Kustomize 구성
│           ├── patch/                 # 패치 파일들
│           └── resources/             # 추가 리소스 (없음)
  • Makefile: apply, delete, preview 등 배포 자동화 명령어
  • kustomize/base/: 모든 환경에 공통 적용될 리소스(Deployment, Service 등)
  • kustomize/overlays/dev/: dev 환경 특화 설정 (이미지 태그, 패치 등)

4. 설치 단계

4.1. Kustomize 구성

4.1.1. kustomization.yaml 구성

kustomize/overlays/dev/kustomization.yaml에서 namespace, resources, patches 등 지정

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: msa
resources:
- ../../base
replicas:
- count: 1
  name: orchestrator-api
- count: 1
  name: project-api
images:
- name: harbor.cnapcloud.com/library/spring-msa-demo
  newName: harbor.cnapcloud.com/library/spring-msa-demo
  newTag: 2f96287
patches:
- path: ./patch/project-env-patch.yaml
  target:
    kind: Deployment
    name: project-api
- path: ./patch/orchestrator-env-patch.yaml
  target:
    kind: Deployment
    name: orchestrator-api
secretGenerator:
- name: keycloak-secret
  literals:
  - realm-url=https://keycloak.cnapcloud.com/realms/cnap
  - client-id=msa
  - client-secret=UVxHOjG05rMLe4CLwkjrlPM9czCjKT4f

4.1.2. 패치 파일 설정

환경별 설정을 위한 패치 파일들:

  • patch/project-env-patch.yaml: Project API 환경 변수 설정
  • patch/orchestrator-env-patch.yaml: Orchestrator API 환경 변수 설정

4.2. 배포 프로세스 (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 msa -w

5. 설치 후 검증

5.1. 리소스 상태 확인

kubectl get pods,svc,ingress -n msa

확인 사항:

  • Pod 상태:
    • orchestrator-api-*: Running (Orchestrator API)
    • project-api-*: Running (Project API)
  • Service 상태:
    • orchestrator-api: ClusterIP
    • project-api: ClusterIP
  • Ingress 상태:
    • msa-demo-ingress: Ingress 리소스 확인

5.2. API 상태 확인

브라우저에서 project, orchestrator 서비스에 대해 swagger-ui에 조회합니다.

이 애플리케이션에 대한 자세한 구성 내역은 다음 블로그를 참고합니다.

6. 운영 및 Troubleshooting

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

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

주요 원인:

  • 이미지 풀 실패 → Harbor 레지스트리 접근 권한 확인
  • 환경 변수 설정 오류 → 패치 파일 확인
  • 리소스 부족 → 노드 리소스 확인

6.2. API 호출 실패

  • Service 확인: kubectl get svc -n msa
  • Endpoint 확인: kubectl get endpoints -n msa
  • 로그 확인: kubectl logs deployment/project-api -n msa

6.3. Istio 관련 문제

  • Sidecar injection 확인: kubectl get pods -n msa -o jsonpath='{.items[*].spec.containers[*].name}'
  • Istio proxy 로그: kubectl logs <pod명> -c istio-proxy -n msa

7. 배포 제거

7.1. MSA-Demo 삭제

make delete DEPLOY_ENV=dev

7.2. Namespace 삭제 (선택사항)

kubectl delete namespace msa

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

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

설치 전:

  • Kubernetes 클러스터 준비 (v1.30+)
  • kubectl, kustomize 설치
  • Keycloak msa client 설정 완료
  • DNS 설정 완료

설치:

  • kustomization.yaml 구성 완료
  • 패치 파일 설정 완료
  • make namespace 실행
  • make preview 실행 및 확인
  • make apply 실행

검증:

  • 모든 Pod이 Running 상태
  • Service 생성 확인
  • API 응답 확인
💬 무료 컨설팅 신청