PitterPetter Infrastructure

PitterPetter 프로젝트의 GCP 기반 Kubernetes 인프라스트럭처를 Terraform으로 관리하는 저장소입니다.
GitOps 기반의 현대적인 CI/CD 파이프라인과 마이크로서비스 아키텍처를 지원합니다.

🏗️ 아키텍처 개요(프로토타입)

┌─────────────────────────────────────────────────────────────────┐
│                        PitterPetter Infrastructure              │
├─────────────────────────────────────────────────────────────────┤
│  🌐 Internet                                                    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              GCP Load Balancer                          │    │
│  │              (34.64.212.163)                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│       │                                                         │
│       ▼                                                         │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              Nginx Ingress Controller                   │    │
│  │              (ingress-nginx)                           │    │
│  └─────────────────────────────────────────────────────────┘    │
│       │                                                         │
│       ├── argocd.pitterpetter.com ──► ArgoCD (GitOps)         │
│       ├── workflows.pitterpetter.com ► Argo Workflows          │
│       ├── rollouts.pitterpetter.com ► Argo Rollouts            │
│       └── api.loventure.us ─────► Microservices                │
│           ├── /api/auth ────────► Auth Service                 │
│           ├── /api/course ──────► Course Service               │
│           └── /api/diaries ─────► Content Service              │
└─────────────────────────────────────────────────────────────────┘

📁 프로젝트 구조

PitterPetter_Infra/
├── 📋 Core Infrastructure
│   ├── main.tf                    # 핵심 인프라 (VPC, 서브넷, GKE 클러스터)
│   ├── gke.tf                    # GKE 노드 풀 및 클러스터 세부 설정
│   ├── networking.tf              # 네트워크 보안 (방화벽, NAT Gateway)
│   └── providers.tf              # Terraform Provider 설정
│
├── 🌐 Ingress & SSL
│   ├── ingress.tf                # Nginx Ingress Controller + API 라우팅
│   ├── swagger_ingress.tf        # Swagger UI Ingress 설정
│   └── ssl_files/                # SSL 인증서 파일들
│
├── 🚀 GitOps & CI/CD
│   ├── argocd.tf                 # ArgoCD (GitOps 배포)
│   ├── workflows.tf              # Argo Workflows (워크플로우 오케스트레이션)
│   └── rollouts.tf               # Argo Rollouts (고급 배포 전략)
│
├── 📊 Monitoring & Observability
│   ├── gmp.tf                    # Google Managed Prometheus 설정
│   └── gmp_dashboard.tf          # GMP 대시보드 구성
│
├── ⚙️ Configuration
│   ├── variables.tf              # 모든 변수 정의 (정리됨)
│   ├── outputs.tf                # 출력값 정의 (향상됨)
│   └── backend.tf                # Terraform State 백엔드 설정
│
├── 🌍 Environment Configs
│   ├── env/
│   │   ├── dev.tfvars           # 개발환경 설정 (4-8노드, e2-standard-2)
│   │   └── prod.tfvars          # 운영환경 설정 (4-8노드, e2-standard-2)
│
├── 🛠️ Scripts & Tools
│   └── scripts/
│       └── cleanup.sh           # 인프라 정리 스크립트
│
├── 📚 Documentation
│   ├── docs/
│   │   ├── QUICKSTART.md        # 5분 빠른 시작 가이드
│   │   ├── INGRESS_GUIDE.md     # Ingress Controller 상세 가이드
│   │   └── GMP_MONITORING_GUIDE.md # GMP 모니터링 가이드
│   └── README.md               # 이 파일

🛠️ 사전 요구사항

필수 도구 설치

# 1. Terraform 설치 (v1.5+)
# macOS
brew install terraform

# Linux
wget https://releases.hashicorp.com/terraform/1.6.0/terraform_1.6.0_linux_amd64.zip
unzip terraform_1.6.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/

# 2. Google Cloud CLI 설치
# macOS
brew install google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash
exec -l $SHELL

# 3. kubectl 설치
# macOS
brew install kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# 4. Helm 설치
# macOS
brew install helm

# Linux
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

GCP 프로젝트 설정

# 1. GCP 프로젝트 생성 및 활성화
gcloud projects create pitterpetter --name="PitterPetter"
gcloud config set project pitterpetter

# 2. 필요한 API 활성화
gcloud services enable container.googleapis.com
gcloud services enable compute.googleapis.com
gcloud services enable storage.googleapis.com
gcloud services enable iam.googleapis.com

# 3. GCP 인증
gcloud auth login
gcloud auth application-default login

# 4. 서비스 계정 생성 (선택사항)
gcloud iam service-accounts create terraform-sa \
    --display-name="Terraform Service Account" \
    --description="Service account for Terraform operations"

🚀 빠른 시작

1. 저장소 클론

git clone <https://github.com/PitterPetter/PitterPetter_Infra.gitl>
cd PitterPetter_Infra

2. 인프라 배포

개발환경 배포

terraform init
terraform plan -var-file="env/dev.tfvars"
terraform apply -var-file="env/dev.tfvars"

운영환경 배포

terraform init
terraform plan -var-file="env/prod.tfvars"
terraform apply -var-file="env/prod.tfvars"

3. 인프라 상태 확인

# 전체 인프라 요약 정보
terraform output infrastructure_summary

# 빠른 접근 명령어들
terraform output quick_access_commands

# 특정 서비스 정보
terraform output argocd_url
terraform output ssl_domain_name

4. 클러스터 연결

# GKE 클러스터 인증 정보 가져오기
gcloud container clusters get-credentials pitterpetter-dev-cluster \
    --region asia-northeast3 \
    --project pitterpetter

# 클러스터 연결 확인
kubectl get nodes
kubectl get namespaces

5. 서비스 접속

ArgoCD 접속

# 포트 포워딩
kubectl port-forward svc/argocd-server -n argocd 8080:443

# 웹 브라우저에서 접속
# https://localhost:8080
# 사용자명: admin
# 비밀번호: dev-admin123! (개발환경)

Argo Workflows 접속

# 포트 포워딩
kubectl port-forward svc/argo-workflows-server -n argo 2746:2746

# 웹 브라우저에서 접속
# https://localhost:2746

Argo Rollouts 접속

# 포트 포워딩
kubectl port-forward svc/argo-rollouts-dashboard -n argo-rollouts 3100:3100

# 웹 브라우저에서 접속
# https://localhost:3100

🏗️ 인프라 구성 요소

🎯 핵심 인프라

Google Kubernetes Engine (GKE): 컨테이너 오케스트레이션
- 클러스터: pitterpetter-dev-cluster (asia-northeast3-b)
- 노드 풀: pitterpetter-nodes (4개 노드, e2-standard-2)
- 자동 스케일링: 4-8개 노드
Virtual Private Cloud (VPC): 네트워크 격리 및 보안
- VPC: pitterpetter-dev-vpc
- 서브넷: pitterpetter-dev-subnet (10.0.0.0/24)
Cloud NAT: 아웃바운드 인터넷 접근
Load Balancer: 고정 IP (34.64.212.163)

🚀 GitOps 및 CI/CD

ArgoCD: GitOps 기반 지속적 배포
- 네임스페이스: argocd
- 접속: https://34.64.212.163 (Host: argo.loventure.us)
Argo Workflows: 워크플로우 오케스트레이션
- 네임스페이스: argo
- 접속: https://34.64.212.163 (Host: workflows.loventure.us)
Argo Rollouts: 고급 배포 전략 (Blue-Green, Canary)
- 네임스페이스: argo-rollouts
- 접속: https://34.64.212.163 (Host: rollouts.loventure.us)

🌐 API 서비스 (마이크로서비스)

Auth Service: 사용자 인증 및 관리
- 엔드포인트: https://api.loventure.us/api/auth/*
- 포트: 8081
Course Service: 코스 관리
- 엔드포인트: https://api.loventure.us/api/course/*
- 포트: 8083
Content Service: 콘텐츠 관리 (일기 등)
- 엔드포인트: https://api.loventure.us/api/diaries/*
- 포트: 8082

🔒 보안 및 모니터링

SSL/TLS: GCP SSL 인증서 (pitterpetter-ssl)
Nginx Ingress Controller: 트래픽 라우팅 및 SSL 종료
Cloud Logging: 중앙화된 로그 관리
Google Managed Prometheus (GMP): 완전 관리형 메트릭 수집
- PodMonitoring: 8개 서비스 메트릭 수집 (애플리케이션 + ELK)
- Alert Rules: 10개 알림 규칙 (핵심 서비스, 인프라, ELK)
- 메트릭 수집 간격: 30초
- 공통 라벨링: cluster, environment, project, service, type
Firewall Rules: 네트워크 보안 정책

📊 Google Managed Prometheus (GMP) 모니터링

모니터링 구성

PodMonitoring 리소스: 5개 (애플리케이션 서비스)
대시보드: Google Cloud Monitoring (5개 위젯)
메트릭 수집: 30초 간격, HTTP 스키마
대상 서비스: Gateway, Auth, Content, Course, AI

대시보드 위젯

CPU 사용률: kubernetes.io/container/cpu/core_usage_time
메모리 사용률: kubernetes.io/container/memory/used_bytes
네트워크 트래픽: 수신/송신 바이트 카운트
Container 재시작: kubernetes.io/container/restart_count

💡 자세한 설정: GMP_MONITORING_GUIDE.md 참조

🔧 개발 워크플로우

일상적인 개발 작업

# 1. 변경사항 계획 확인
terraform plan -var-file="env/dev.tfvars"

# 2. 변경사항 적용
terraform apply -var-file="env/dev.tfvars"

# 3. 상태 확인
terraform show
terraform output

# 4. 인프라 요약 확인
terraform output infrastructure_summary

새로운 환경 변수 추가

variables.tf에 변수 정의 (기본값 제거 권장)
env/dev.tfvars에 개발환경 값 설정
env/prod.tfvars에 운영환경 값 설정
코드에서 변수 사용

새로운 리소스 추가

적절한 .tf 파일에 리소스 정의
outputs.tf에 필요한 출력값 추가
terraform plan으로 계획 확인
terraform apply로 적용

🆕 최근 업데이트 (v2.1)

✨ 주요 개선사항

환경별 설정 분리: env/ 디렉토리로 환경별 변수 관리
변수 정리: 사용되지 않는 변수 제거 및 최적화
Output 향상: 인프라 요약 정보 및 빠른 접근 명령어 추가
모니터링 강화: GMP 대시보드 및 상세 모니터링 설정
Swagger UI: API 문서화를 위한 Swagger UI Ingress 추가
인프라 안정성: GKE 클러스터 및 네트워킹 구성 최적화
보안 강화: 방화벽 규칙 및 SSL 인증서 관리 개선

🔧 설정 변경사항

variables.tf: 불필요한 변수 제거, 코드 정리
outputs.tf: infrastructure_summary, quick_access_commands 추가
env/: 환경별 설정 파일 분리 (dev.tfvars, prod.tfvars)
gmp_dashboard.tf: 모니터링 대시보드 추가
gke.tf: GKE 클러스터 설정 최적화
ingress.tf: Ingress Controller 및 라우팅 규칙 개선
networking.tf: 네트워크 보안 정책 강화
argocd.tf: ArgoCD 배포 설정 개선

🌐 서비스 접속 방법

🚀 ArgoCD (GitOps 배포 관리)

접속 정보:

URL: https://34.64.212.163 (Host: argo.loventure.us)
사용자명: admin
비밀번호: dev-admin123!

접속 방법:

브라우저 접속 (권장):

# 브라우저에서 https://34.64.212.163 접속
# Host 헤더를 argo.loventure.us로 설정하거나
# curl로 테스트: curl -H "Host: argo.loventure.us" -k https://34.64.212.163

보안 경고가 나타나면 "고급" → "안전하지 않은 사이트로 이동" 클릭

🔄 Argo Workflows (워크플로우 오케스트레이션)

접속 정보:

URL: https://34.64.212.163 (Host: workflows.loventure.us)
Port Forward: kubectl port-forward svc/argo-workflows-server -n argo 2746:2746

🎯 Argo Rollouts (고급 배포 전략)

접속 정보:

URL: https://34.64.212.163 (Host: rollouts.loventure.us)
Port Forward: kubectl port-forward svc/argo-rollouts-dashboard -n argo-rollouts 3100:3100

🌐 API 서비스 (마이크로서비스)

기본 URL: https://api.loventure.us

서비스별 엔드포인트:

# Auth Service (사용자 인증)
curl -k https://api.loventure.us/api/auth/health
curl -k https://api.loventure.us/oauth2/authorize

# Course Service (코스 관리)
curl -k https://api.loventure.us/api/course/health
curl -k https://api.loventure.us/api/course/courses

# Content Service (일기 관리)
curl -k https://api.loventure.us/api/diaries/health
curl -k https://api.loventure.us/api/diaries/diaries

📚 Swagger UI (API 문서화)

Swagger UI 접속:

Auth Service: https://swagger-auth.loventure.us
Content Service (Diaries): https://swagger-diaries.loventure.us
Course Service: https://swagger-courses.loventure.us

Swagger UI 상태 확인:

# 모든 Swagger Ingress 확인
kubectl get ingress -n loventure-app | grep swagger

# 특정 Swagger UI 테스트
curl -H "Host: swagger-auth.loventure.us" -k https://34.64.212.163

🔍 시스템 상태 확인

# Ingress Controller 상태
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx

# 모든 Ingress 확인
kubectl get ingress -A

# 서비스 상태 확인
kubectl get pods -n loventure-app
kubectl get svc -n loventure-app

📊 Google Managed Prometheus (GMP) 모니터링

Cloud Monitoring URL: https://console.cloud.google.com/monitoring

GMP 상태 확인:

# GMP Operator 상태
kubectl get pods -n gmp-system

# PodMonitoring 리소스 확인
kubectl get podmonitorings -A

# 대시보드 확인
# Google Cloud Console > Monitoring > Dashboards > "PitterPetter GMP Dashboard"

# ClusterPodMonitoring 확인
kubectl get clusterpodmonitorings

메트릭 수집 확인:

# 특정 서비스 메트릭 확인
kubectl describe podmonitoring gateway-podmonitoring

# 알림 정책 확인
kubectl describe rules <rule-name>

Cloud Monitoring에서 확인할 수 있는 메트릭:

애플리케이션 메트릭: CPU, 메모리, 응답 시간, 요청 수
ELK 스택 메트릭: Elasticsearch 클러스터 상태, 로그 처리량
인프라 메트릭: 노드 상태, 디스크 사용량, 네트워크 트래픽

🧹 인프라 정리

자동 정리 (권장)

# cleanup.sh 스크립트 실행
chmod +x scripts/cleanup.sh
./scripts/cleanup.sh

수동 정리

# 1. Kubernetes 리소스 정리
kubectl delete namespace argocd --force --grace-period=0
kubectl delete namespace argo --force --grace-period=0
kubectl delete namespace argo-rollouts --force --grace-period=0

# 2. Terraform destroy
terraform destroy -var-file="env/dev.tfvars" -auto-approve

🚨 문제 해결 가이드

🔧 자주 발생하는 문제들

1. GCP 인증 오류

# 문제: Authentication error
# 해결: GCP 인증 재설정
gcloud auth login
gcloud auth application-default login
gcloud config set project pitterpetter

# 추가 확인
gcloud auth list
gcloud config get-value project

2. Terraform Provider 오류

# 문제: Provider not found
# 해결: Terraform 초기화
terraform init -upgrade
terraform providers

# 백엔드 문제 시
terraform init -reconfigure

3. Kubernetes 네임스페이스 삭제 타임아웃

# 문제: Namespace stuck in Terminating state
# 해결: 강제 삭제
kubectl delete namespace argocd --force --grace-period=0
kubectl delete namespace argo --force --grace-period=0
kubectl delete namespace argo-rollouts --force --grace-period=0
kubectl delete namespace loventure-app --force --grace-period=0

# Finalizers 제거 (필요시)
kubectl patch namespace argocd -p '{"metadata":{"finalizers":null}}' --type=merge

4. GKE 클러스터 삭제 지연

# 문제: Cluster deletion timeout
# 해결: 수동 삭제
gcloud container clusters delete pitterpetter-dev-cluster \
    --zone asia-northeast3-b \
    --project=pitterpetter --quiet

# Terraform State에서 제거
terraform state rm google_container_cluster.primary

5. Terraform State 불일치

# 문제: State drift
# 해결: State 새로고침
terraform refresh -var-file="env/dev.tfvars"
terraform plan -var-file="env/dev.tfvars"

# 특정 리소스만 새로고침
terraform refresh -target=google_container_cluster.primary

6. Ingress Controller 접속 불가

# 문제: 404 Not Found 또는 연결 불가
# 해결: Ingress Controller 상태 확인
kubectl get pods -n ingress-nginx
kubectl get svc -n ingress-nginx
kubectl describe pod -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx

# Ingress 리소스 확인
kubectl get ingress -A
kubectl describe ingress -n argocd argocd-ingress

7. ArgoCD 접속 불가

# 문제: ArgoCD 웹 UI 접속 안됨
# 해결: ArgoCD 상태 확인
kubectl get pods -n argocd
kubectl get svc -n argocd
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server

# 비밀번호 확인
kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d

8. API 서비스 502/503 오류

# 문제: API 엔드포인트 응답 없음
# 해결: 서비스 상태 확인
kubectl get pods -n loventure-app
kubectl get svc -n loventure-app
kubectl describe pod -n loventure-app -l app=auth-service

# 로그 확인
kubectl logs -n loventure-app -l app=auth-service --tail=100

9. SSL 인증서 오류

# 문제: SSL 인증서 관련 오류
# 해결: 인증서 상태 확인
gcloud compute ssl-certificates list
kubectl get secrets -n argocd | grep tls

# Ingress TLS 설정 확인
kubectl describe ingress -n argocd argocd-ingress

10. CPU/메모리 부족 오류

# 문제: Pod가 Pending 상태 또는 OOMKilled
# 해결: 리소스 확인 및 조정
kubectl top nodes
kubectl top pods -A
kubectl describe node

# 노드 스케일링
kubectl scale deployment --replicas=1 -n argocd argocd-server

디버깅 명령어

# Terraform 상태 확인
terraform show
terraform state list
terraform output

# GCP 리소스 확인
gcloud compute instances list
gcloud container clusters list
gcloud compute networks list

# Kubernetes 리소스 확인
kubectl get all --all-namespaces
kubectl describe nodes
kubectl logs -n argocd -l app.kubernetes.io/name=argocd

💰 비용 최적화

💡 현재 비용 최적화 설정

개발환경 (dev.tfvars):

선점형 인스턴스: node_preemptible = true (최대 80% 비용 절약)
머신 타입: e2-standard-2 (2 vCPU, 8GB RAM)
노드 수: 4개 (자동 스케일링: 4-8개)
예상 월 비용: ~$50-80 (선점형 인스턴스 사용 시)

운영환경 (prod.tfvars):

일반 인스턴스: node_preemptible = false (안정성 우선)
머신 타입: e2-standard-2 (2 vCPU, 8GB RAM)
노드 수: 4개 (자동 스케일링: 4-6개)
예상 월 비용: ~$200-300

📊 비용 모니터링

# GCP 비용 확인
gcloud billing budgets list --billing-account=YOUR_BILLING_ACCOUNT

# 리소스 사용량 확인
gcloud compute instances list --filter="status:RUNNING"
gcloud container clusters list

# 특정 프로젝트 비용 확인
gcloud billing accounts list
gcloud billing budgets list --billing-account=YOUR_BILLING_ACCOUNT_ID

🚀 CI/CD 통합

GitHub Actions 예시

name: Deploy Infrastructure
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
      - name: Setup GCP
        uses: google-github-actions/setup-gcloud@v1
        with:
          service_account_key: ${{ secrets.GCP_SA_KEY }}
      - name: Terraform Init
        run: cd terraform && terraform init
      - name: Terraform Plan
        run: cd terraform && terraform plan -var-file="environments/dev.tfvars"
      - name: Terraform Apply
        if: github.ref == 'refs/heads/main'
        run: cd terraform && terraform apply -var-file="environments/dev.tfvars" -auto-approve

📚 추가 자료

프로젝트 문서

빠른 시작 가이드: 새로운 팀원을 위한 5분 설정 가이드
Ingress Controller 가이드: Nginx Ingress Controller 상세 가이드

Name		Name	Last commit message	Last commit date
.githooks		.githooks
.github		.github
docs		docs
env		env
scripts		scripts
.gitignore		.gitignore
.terraform.lock.hcl		.terraform.lock.hcl
README.md		README.md
argocd.tf		argocd.tf
backend.tf		backend.tf
gke.tf		gke.tf
gmp.tf		gmp.tf
gmp_dashboard.tf		gmp_dashboard.tf
ingress.tf		ingress.tf
main.tf		main.tf
networking.tf		networking.tf
outputs.tf		outputs.tf
providers.tf		providers.tf
rollouts.tf		rollouts.tf
swagger_ingress.tf		swagger_ingress.tf
variables.tf		variables.tf
workflows.tf		workflows.tf

Latest commit

History

Folders and files

Repository files navigation

PitterPetter Infrastructure

🏗️ 아키텍처 개요(프로토타입)

📁 프로젝트 구조

🛠️ 사전 요구사항

필수 도구 설치

GCP 프로젝트 설정

🚀 빠른 시작

1. 저장소 클론

2. 인프라 배포

개발환경 배포

운영환경 배포

3. 인프라 상태 확인

4. 클러스터 연결

5. 서비스 접속

ArgoCD 접속

Argo Workflows 접속

Argo Rollouts 접속

🏗️ 인프라 구성 요소

🎯 핵심 인프라

🚀 GitOps 및 CI/CD

🌐 API 서비스 (마이크로서비스)

🔒 보안 및 모니터링

📊 Google Managed Prometheus (GMP) 모니터링

모니터링 구성

대시보드 위젯

🔧 개발 워크플로우

일상적인 개발 작업

새로운 환경 변수 추가

새로운 리소스 추가

🆕 최근 업데이트 (v2.1)

✨ 주요 개선사항

🔧 설정 변경사항

🌐 서비스 접속 방법

🚀 ArgoCD (GitOps 배포 관리)

🔄 Argo Workflows (워크플로우 오케스트레이션)

🎯 Argo Rollouts (고급 배포 전략)

🌐 API 서비스 (마이크로서비스)

📚 Swagger UI (API 문서화)

🔍 시스템 상태 확인

📊 Google Managed Prometheus (GMP) 모니터링

🧹 인프라 정리

자동 정리 (권장)

수동 정리

🚨 문제 해결 가이드

🔧 자주 발생하는 문제들

1. GCP 인증 오류

2. Terraform Provider 오류

3. Kubernetes 네임스페이스 삭제 타임아웃

4. GKE 클러스터 삭제 지연

5. Terraform State 불일치

6. Ingress Controller 접속 불가

7. ArgoCD 접속 불가

8. API 서비스 502/503 오류

9. SSL 인증서 오류

10. CPU/메모리 부족 오류

디버깅 명령어

💰 비용 최적화

💡 현재 비용 최적화 설정

📊 비용 모니터링

🚀 CI/CD 통합

GitHub Actions 예시

📚 추가 자료

프로젝트 문서

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages