Cloud SQL 인프라 관리

개요

DTA-WIDE 시스템은 관계형 데이터베이스 관리를 위해 Google Cloud SQL을 사용합니다. 이 문서는 Terraform과 Terragrunt를 통한 Cloud SQL 인스턴스 관리 방법을 설명합니다.

아키텍처

데이터베이스 구성

DTA-WIDE 시스템은 환경별로 다음과 같은 Cloud SQL 인스턴스를 사용합니다:

환경	인스턴스 이름	데이터베이스 종류	버전	고가용성	머신 타입
개발(dev)	db-dta-wide-dev	PostgreSQL	16	비활성화	db-g1-small
스테이징(stage)	db-dta-wide-stage	PostgreSQL	16	활성화	db-n1-standard-1
프로덕션(prod)	db-dta-wide-prod	PostgreSQL	16	활성화	db-n1-standard-2

네트워크 구성

모든 Cloud SQL 인스턴스는 비공개 IP를 사용하여 VPC 네트워크 내에서만 접근 가능합니다:

VPC 네트워크: dta-cloud-de-[dev|stage|prod]-vpc
서비스 연결: 비공개 서비스 액세스 사용
SSL 연결: 필수

비공개 IP 사용을 위한 사전 요구사항

Cloud SQL 인스턴스를 비공개 IP로 배포하기 전에 다음 사전 요구사항을 충족해야 합니다:

Service Networking API 활성화
비공개 서비스 액세스 할당 IP 범위 생성
VPC 피어링 연결 구성

이 설정은 네트워크 모듈 배포 후, Cloud SQL 배포 전에 완료해야 합니다. 자세한 구성 방법은 네트워크 문서의 비공개 서비스 액세스 구성 섹션을 참조하세요.

주의: 이 단계를 생략하면 SERVICE_NETWORKING_NOT_ENABLED 오류가 발생하여 Cloud SQL 인스턴스 생성이 실패합니다.

Terraform 모듈

Cloud SQL 인스턴스는 프로젝트 내 Terraform 모듈(infrastructure/terraform/modules/cloudsql)을 사용하여 관리됩니다.

주요 기능

MySQL/PostgreSQL/SQL Server 인스턴스 생성
데이터베이스 및 사용자 관리
백업 및 복구 설정
네트워크 보안 구성
고가용성 구성
유지보수 일정 관리

모듈 구조

infrastructure/
└── terraform/
    └── modules/
        └── cloudsql/
            ├── main.tf        # 리소스 정의
            ├── variables.tf   # 입력 변수
            ├── outputs.tf     # 출력 변수
            └── README.md      # 사용 가이드

Terragrunt 구성

환경별 Cloud SQL 인스턴스는 Terragrunt를 통해 관리됩니다:

infrastructure/
└── terragrunt/
    ├── dev/
    │   └── cloudsql/
    │       └── terragrunt.hcl   # 개발 환경 구성
    ├── stage/
    │   └── cloudsql/
    │       └── terragrunt.hcl   # 스테이징 환경 구성
    └── prod/
        └── cloudsql/
            └── terragrunt.hcl   # 프로덕션 환경 구성

환경별 구성

개발 환경

개발 환경은 비용 효율성을 위해 최소한의 리소스로 구성됩니다:

# infrastructure/terragrunt/dev/cloudsql/terragrunt.hcl
inputs = {
  instance_name    = "db-dta-wide-dev"
  machine_type     = "db-g1-small"
  database_version = "POSTGRES_16"
  high_availability = false
  # ... 기타 설정
}

프로덕션 환경

프로덕션 환경은 높은 신뢰성과 성능을 위해 구성됩니다:

# infrastructure/terragrunt/prod/cloudsql/terragrunt.hcl
inputs = {
  instance_name    = "db-dta-wide-prod"
  machine_type     = "db-n1-standard-2"
  database_version = "POSTGRES_16"
  high_availability = true
  # ... 기타 설정
}

데이터베이스 관리

데이터베이스 생성

모든 환경에는 공통 데이터베이스와 환경별 데이터베이스가 구성됩니다:

# 기본 데이터베이스
create_default_database = true
default_database_name   = "dta_main"

# 추가 데이터베이스
additional_databases = {
  "analytics" = {},
  "reporting" = {}
}

사용자 관리

보안상의 이유로 데이터베이스 사용자 비밀번호는 Terraform에서 직접 관리하지 않고 Secret Manager와 통합하여 관리합니다:

# Secret Manager에서 관리하므로 Terraform에서는 생성하지 않음
create_default_user = false

백업 및 복구

백업 정책

모든 환경은 자동 백업이 구성되어 있습니다:

backup_enabled      = true
backup_start_time   = "01:00"  # 매일 01:00 UTC

PostgreSQL 16에서는 특별히 시점 복구(Point-in-Time Recovery, PITR)를 위한 WAL(Write-Ahead Logging)이 자동으로 설정됩니다.

보관 기간

환경별 백업 보관 기간:

개발: 7일
스테이징: 7일
프로덕션: 14일

복구 절차

Google Cloud Console에서 인스턴스의 백업 탭으로 이동
복구하려는 백업 선택
복원 작업 실행 (기존 인스턴스로 복원 또는 새 인스턴스 생성)

보안 관행

비공개 IP 주소만 사용
SSL 연결 필수
최소 권한 원칙에 따른 서비스 계정 관리
데이터베이스 비밀번호는 Secret Manager에서 관리
모든 인스턴스에 삭제 보호 활성화

모니터링 및 알림

Cloud SQL 인스턴스는 다음 지표에 대한 알림이 구성되어 있습니다:

CPU 사용률 (80% 이상)
메모리 사용률 (85% 이상)
디스크 사용률 (90% 이상)
연결 수 (최대 연결의 80% 이상)
복제 지연 (60초 이상, 고가용성 구성만 해당)

유지보수 관리

유지보수 일정

각 환경별 정기 유지보수 일정:

개발: 매주 화요일 03:00 UTC
스테이징: 매주 목요일 03:00 UTC
프로덕션: 매주 일요일 02:00 UTC

버전 업그레이드

마이너 버전 업그레이드는 Google Cloud에서 자동으로 관리하지만 메이저 버전 업그레이드는 다음 절차를 따릅니다:

개발 환경에서 먼저 테스트
애플리케이션 호환성 검증
스테이징 환경으로 롤아웃
최종 검증 후 프로덕션 환경으로 업그레이드

성능 최적화

인스턴스 크기 조정

각 환경의 인스턴스 크기는 워크로드에 맞게 조정됩니다:

# 개발 환경
machine_type = "db-g1-small"  # 공유 코어, 1.7GB 메모리

# 프로덕션 환경
machine_type = "db-n1-standard-2"  # 2 vCPU, 7.5GB 메모리

데이터베이스 플래그

성능 최적화를 위한 PostgreSQL 데이터베이스 플래그:

# 프로덕션 환경
database_flags = {
  "max_connections"           = "1000"
  "log_min_duration_statement" = "1000"  # 1초 이상 쿼리 로깅
  "shared_buffers"            = "1048576"  # 1GB
  "work_mem"                  = "16384"    # 16MB
  "maintenance_work_mem"      = "131072"   # 128MB
  "effective_cache_size"      = "3145728"  # 3GB
}

비용 최적화

개발 및 테스트 환경에서의 비용 최적화 전략:

소규모 인스턴스 사용 (db-g1-small)
고가용성 비활성화
백업 보관 기간 최소화 (7일)
자동 중지/시작 스케줄링 (개발 시간 외 중지)

PostgreSQL 특화 기능

PostgreSQL 16은 다음과 같은 특별한 기능을 제공합니다:

논리적 복제(Logical Replication): 테이블 단위 복제 지원
JSON 및 JSONB 데이터 타입: 효율적인 JSON 데이터 저장 및 쿼리
확장 기능(Extensions): PostGIS, pgvector 등 다양한 확장 모듈 지원
고급 인덱싱: 부분 인덱스, 표현식 인덱스, GiST/GIN/SP-GiST 인덱스 등
Row-Level Security: 행 수준의 접근 제어

Cloud SQL Studio 접근 가이드

Cloud SQL Studio는 Google Cloud Console에서 제공하는 웹 기반 SQL 클라이언트로, 데이터베이스에 직접 연결하여 쿼리를 실행할 수 있습니다.

접근 방법

Google Cloud Console에서 Cloud SQL 인스턴스 목록으로 이동
해당 인스턴스를 선택하고 "Cloud SQL Studio 열기" 버튼 클릭
로그인 정보 입력:
- 사용자 이름: postgres 또는 admin (관리자 권한이 필요한 경우 postgres 사용)
- 비밀번호: Terraform 적용 시 설정한 비밀번호

연결 정보

개발 환경 Cloud SQL 인스턴스의 연결 이름은 다음과 같습니다:

dta-cloud-de-dev:europe-west3:db-dta-wide-dev

이 연결 이름은 다음과 같은 형식을 따릅니다:

[프로젝트 ID]:[리전]:[인스턴스 이름]

이 연결 이름은 다음과 같은 상황에서 필요합니다:

Cloud SQL Auth Proxy 사용 시
JDBC/ODBC 연결 문자열 구성 시
외부 툴(예: DBeaver, pgAdmin)에서 연결 설정 시
CLI 도구(예: psql)에서 연결 시

주의사항

PostgreSQL 인스턴스는 기본적으로 postgres 사용자가 생성됩니다.
Cloud SQL Studio에 로그인하려면 이 사용자의 비밀번호가 설정되어 있어야 합니다.
사용자 계정을 Terraform으로 관리하지 않는 경우 GCP 콘솔에서 직접 비밀번호를 설정해야 합니다.
PostgreSQL 인스턴스의 사용자는 host 필드를 설정할 수 없습니다 (MySQL과 다름).

Cloud SQL Terragrunt 실행 방법

Cloud SQL 인스턴스를 생성하거나 구성을 변경하기 위한 Terragrunt 실행 방법을 설명합니다.

기본 명령어

1. 초기 설정 및 계획 확인

# 개발 환경
cd infrastructure/terragrunt/dev/cloudsql

# Terragrunt 초기화
terragrunt init

# 변경 사항 계획 확인
terragrunt plan

2. 변경 사항 적용

방법 1: 직접 적용 (단순한 방법)

# 변경 사항 적용 (승인 필요)
terragrunt apply

# 또는 자동 승인으로 적용
terragrunt apply -auto-approve

방법 2: 계획 파일 사용 (권장 방법)

# 변경 계획을 파일로 저장
terragrunt plan -out=plan.tfplan

# 저장된 계획 파일 적용 (승인 메시지 없음)
terragrunt apply plan.tfplan

계획 파일 사용의 장점:

계획 검토 시점과 적용 시점의 변경 사항이 동일하게 유지됩니다.
승인 과정이 생략되어 CI/CD 파이프라인에 적합합니다.
변경 이력 관리에 유용하며, 파일로 저장해 두면 나중에 참조할 수 있습니다.
여러 사람이 변경 사항을 검토할 수 있습니다.

주의: 계획 파일은 민감한 정보를 포함할 수 있으므로 안전하게 관리해야 합니다.

3. 상태 확인

# 현재 상태 확인
terragrunt state list

# 특정 리소스 상태 확인
terragrunt state show google_sql_database_instance.main

환경별 적용 순서

Cloud SQL 변경은 항상 다음 순서로 적용하는 것이 좋습니다:

개발 환경 적용 및 테스트

cd infrastructure/terragrunt/dev/cloudsql
terragrunt apply

변경 사항 검증
- 애플리케이션 연결 테스트
- 성능 모니터링
- 기능 테스트

스테이징 환경 적용

cd infrastructure/terragrunt/stage/cloudsql
terragrunt apply

프로덕션 환경 적용 (유지보수 시간에 수행)

cd infrastructure/terragrunt/prod/cloudsql
terragrunt apply

고급 사용법

특정 리소스만 변경

# 데이터베이스 인스턴스 설정만 변경
terragrunt apply -target=google_sql_database_instance.main

# 특정 데이터베이스만 변경
terragrunt apply -target=google_sql_database.default

변경 사항 사전 저장

# 변경 계획 파일로 저장
terragrunt plan -out=cloudsql_changes.tfplan

# 저장된 계획 적용
terragrunt apply cloudsql_changes.tfplan

디버그 모드 실행

# 상세 로그 출력으로 실행
TF_LOG=DEBUG terragrunt apply

주의사항

백업 확인: 중요한 변경 전에는 항상 최신 백업이 있는지 확인하세요.
다운타임 고려: 일부 설정 변경(머신 유형, 스토리지 설정 등)은 인스턴스 재시작이 필요합니다.
점진적 변경: 큰 변경사항은 작은 단계로 나누어 적용하는 것이 안전합니다.
권한 확인: Terragrunt 실행 계정에 필요한 권한이 있는지 확인하세요.
계획 검토: terragrunt plan 출력을 꼼꼼히 검토하여 의도하지 않은 변경이 없는지 확인하세요.
데이터베이스 인코딩 차이: PostgreSQL과 MySQL은 지원하는 문자 인코딩이 다릅니다.
- PostgreSQL: UTF8, ko_KR.UTF8 등을 사용
- MySQL: utf8mb4, utf8mb4_general_ci 등을 사용
- PostgreSQL에서 MySQL용 인코딩(utf8mb4)을 사용하면 오류가 발생합니다.
PostgreSQL 콜레이션 호환성: PostgreSQL 데이터베이스를 추가로 생성할 때는 템플릿 데이터베이스와 호환되는 콜레이션을 사용해야 합니다.
- 기본 템플릿 데이터베이스는 보통 en_US.UTF8 콜레이션을 사용합니다.
- 다른 콜레이션(예: ko_KR.UTF8)을 사용하려면 먼저 템플릿 데이터베이스의 콜레이션을 변경해야 합니다.
- 모듈에서는 기본적으로 en_US.UTF8 콜레이션을 사용합니다.

참고 자료

TBD

개요​

아키텍처​

데이터베이스 구성​

네트워크 구성​

비공개 IP 사용을 위한 사전 요구사항​

Terraform 모듈​

주요 기능​

모듈 구조​

Terragrunt 구성​

환경별 구성​

개발 환경​

프로덕션 환경​

데이터베이스 관리​

데이터베이스 생성​

사용자 관리​

백업 및 복구​

백업 정책​

보관 기간​

복구 절차​

보안 관행​

모니터링 및 알림​

유지보수 관리​

유지보수 일정​

버전 업그레이드​

성능 최적화​

인스턴스 크기 조정​

데이터베이스 플래그​

비용 최적화​

PostgreSQL 특화 기능​

Cloud SQL Studio 접근 가이드​

접근 방법​

연결 정보​

주의사항​

Cloud SQL Terragrunt 실행 방법​

기본 명령어​

1. 초기 설정 및 계획 확인​

2. 변경 사항 적용​

방법 1: 직접 적용 (단순한 방법)​

방법 2: 계획 파일 사용 (권장 방법)​

3. 상태 확인​

환경별 적용 순서​

고급 사용법​

특정 리소스만 변경​

변경 사항 사전 저장​

디버그 모드 실행​

주의사항​

참고 자료​

개요

아키텍처

데이터베이스 구성

네트워크 구성

비공개 IP 사용을 위한 사전 요구사항

Terraform 모듈

주요 기능

모듈 구조

Terragrunt 구성

환경별 구성

개발 환경

프로덕션 환경

데이터베이스 관리

데이터베이스 생성

사용자 관리

백업 및 복구

백업 정책

보관 기간

복구 절차

보안 관행

모니터링 및 알림

유지보수 관리

유지보수 일정

버전 업그레이드

성능 최적화

인스턴스 크기 조정

데이터베이스 플래그

비용 최적화

PostgreSQL 특화 기능

Cloud SQL Studio 접근 가이드

접근 방법

연결 정보

주의사항

Cloud SQL Terragrunt 실행 방법

기본 명령어

1. 초기 설정 및 계획 확인

2. 변경 사항 적용

방법 1: 직접 적용 (단순한 방법)

방법 2: 계획 파일 사용 (권장 방법)

3. 상태 확인

환경별 적용 순서

고급 사용법

특정 리소스만 변경

변경 사항 사전 저장

디버그 모드 실행

주의사항

참고 자료