Deployment and Operations

Deployment and Operations

이 페이지는 dev·prod Workflow 실행, 배포 산출물, 롤백과 운영 확인을 다룹니다. 버전 결정, release/v*·hotfix/* 흐름, 태그와 GitHub Release 정책은 Release Management를 먼저 확인합니다.

배포 흐름

dev와 prod Lambda 배포는 수동 workflow_dispatch입니다. dev는 Lambda Version과 Alias만 갱신합니다. prod는 Release Management에서 확정한 main commit과 버전으로 실행합니다.

flowchart TB
    Start["GitHub Actions 수동 실행"] --> Target{"배포 대상"}

    Target -->|dev| DevRef["배포할 브랜치 선택"]
    Target -->|prod| ProdRef["main 선택 · 버전 입력"]
    ProdRef --> Preflight["사전 검증<br/>main · 버전 · 중복 태그"]

    DevRef --> Migration["DB 마이그레이션"]
    Preflight --> Migration
    Migration --> Build["테스트 · 빌드 · S3 업로드"]
    Build --> Publish["Lambda Version 게시"]
    Publish --> Alias["Alias 이동 · 검증"]

    Alias --> Result{"배포 기록"}
    Result -->|dev| DevDone["배포 완료<br/>태그 · Release 없음"]
    Result -->|prod| Metadata["Summary · metadata"]
    Metadata --> ProdDone["태그 · GitHub Release"]

Loading

사용하는 Workflow입니다.

Workflow	용도
CI (Gradle)	dev, main push·PR에서 ./gradlew check
Flyway Migration for DB schema	dev·prod DB 마이그레이션 단독 실행
Deploy to Dev Lambda	dev 마이그레이션 후 Lambda 배포
Deploy to Prod Lambda	prod 마이그레이션 후 Lambda 배포

필요한 GitHub 설정

Repository Variables입니다.

• dev는 DEV_AWS_REGION, DEV_LAMBDA_FUNCTION_NAME, DEV_LAMBDA_ALIAS, DEV_LAMBDA_ARTIFACT_BUCKET을 사용합니다.
• prod는 PROD_AWS_REGION, PROD_LAMBDA_FUNCTION_NAME, PROD_LAMBDA_ALIAS, PROD_LAMBDA_ARTIFACT_BUCKET을 사용합니다.

Secrets입니다.

• AWS 배포는 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY를 사용합니다.
• Flyway dev는 DEV_FLYWAY_DB_URL, DEV_FLYWAY_DB_USER, DEV_FLYWAY_DB_PASSWORD를 사용합니다.
• Flyway prod는 PROD_FLYWAY_DB_URL, PROD_FLYWAY_DB_USER, PROD_FLYWAY_DB_PASSWORD를 사용합니다.

값을 Wiki나 Actions 로그에 출력하지 않습니다.

dev 배포

1. 대상 변경이 dev에 포함됐는지 확인합니다.
2. Actions에서 Deploy to Dev Lambda를 선택합니다.
3. 실행할 ref를 확인하고 Workflow를 시작합니다.
4. Migrate dev DB schema가 성공했는지 확인합니다.
5. 테스트, ZIP 생성, S3 업로드, Lambda Version 게시를 확인합니다.
6. Summary의 Published Version과 Alias Version이 같은지 확인합니다.
7. dev Health, Swagger, 변경 endpoint를 smoke test합니다.

dev 배포 Workflow는 Lambda 코드와 Alias만 갱신합니다. 런타임 환경 변수, IAM, Layer, Extension은 관리하지 않습니다. dev 배포 전에도 대상 Lambda의 SPRING_PROFILES_ACTIVE, DB, SQS, HMAC, S3 설정을 별도로 확인합니다.

prod 배포 실행

prod Workflow는 main에서만 실행합니다. Actions 실행 ref가 다르면 preflight에서 실패하며 Migration을 시작하지 않습니다. Workflow 안의 마이그레이션은 prod GitHub Environment의 승인 규칙을 따릅니다.

Workflow dispatch 시점의 main commit SHA를 배포 단위로 고정합니다. Migration, Lambda build, S3 Object, Git 태그와 GitHub Release가 모두 같은 commit SHA를 사용합니다.

prod Flyway migration은 배포 직전까지 트래픽을 처리하는 이전 Lambda 코드와 backward compatible해야 합니다. Migration 성공 뒤 테스트·빌드·Lambda 게시가 실패하면 이전 Alias가 계속 트래픽을 처리하므로 새 schema에서 이전 코드가 정상 동작해야 합니다.

확인 순서입니다.

1. Release Management의 정식 릴리즈 또는 hotfix 사전 조건을 충족했고 대상 변경이 main에 포함됐는지 확인합니다.
2. Actions에서 Deploy to Prod Lambda의 ref를 main으로 선택하고 확정한 버전을 입력해 수동 실행합니다.
3. preflight에서 main, 엄격한 버전 형식, be-v{버전} 태그 중복 검증이 성공했는지 확인합니다.
4. Flyway info에서 예상한 버전만 Pending이고 이전 Lambda 코드와 호환되는지 확인합니다.
5. Migration, Test, Build, Publish가 모두 성공했는지 확인합니다.
6. Alias가 새 Version을 가리키는지 확인합니다.
7. Alias 검증 뒤 Actions Summary와 deployment metadata artifact가 생성됐는지 확인합니다.
8. 같은 commit SHA에 be-v{버전} annotated tag와 GitHub Release가 생성됐는지 확인합니다. Release 본문의 제품 버전, commit SHA, Lambda published version과 alias version도 대조합니다.
9. /health, /actuator/health, 핵심 인증 API를 확인합니다.
10. Sentry와 CloudWatch에서 새 오류가 증가하지 않는지 확인합니다.

prod Lambda에는 다음 런타임 설정이 외부 인프라에서 명시돼야 합니다.

• SPRING_PROFILES_ACTIVE=prod.
• prod DB와 OIDC·JWT 설정.
• prod SQS Queue URL과 HMAC Secret.
• prod S3 Bucket, Prefix, Region.

application.yml의 S3 기본값은 develop-shadow용입니다. prod에서 SCRAPING_RESULT_BUCKET과 SCRAPING_RESULT_PREFIX를 생략하면 잘못된 환경의 결과를 보게 될 수 있습니다.

배포 산출물

lambdaZip은 다음 파일을 만듭니다.

build/distributions/haksa-lambda.zip

Workflow는 commit SHA를 포함한 S3 Key로 ZIP을 올리고 새 Lambda Version을 게시합니다. Alias 검증이 성공하면 Actions Summary와 deployment metadata artifact에 release version, release tag, commit SHA, function, alias, S3 key, published version, alias version을 기록합니다. 태그와 GitHub Release 정책, 부분 실패 복구는 Release Management를 따릅니다.

롤백

애플리케이션 롤백은 직전 정상 Lambda Version으로 Alias를 되돌리는 방식입니다. 이전 Version은 Actions Summary와 deployment metadata artifact에서 확인합니다.

aws lambda update-alias \
  --function-name "$LAMBDA_FUNCTION_NAME" \
  --name "$LAMBDA_ALIAS" \
  --function-version "$PREVIOUS_VERSION"

aws lambda get-alias \
  --function-name "$LAMBDA_FUNCTION_NAME" \
  --name "$LAMBDA_ALIAS" \
  --query 'FunctionVersion' \
  --output text

DB 마이그레이션은 Lambda Alias와 함께 자동 롤백되지 않습니다. 적용된 Migration 파일도 되돌려 수정하지 않습니다. 스키마 보정은 데이터 보존과 이전 애플리케이션 호환성을 확인한 다음 version의 forward migration으로 수행합니다.

운영 확인 지점

Maintenance Event

같은 Lambda Handler는 HTTP API 외에 EventBridge Scheduler event도 처리합니다. source=eventbridge.scheduler이고 task가 있으면 다음 작업을 실행합니다.

• SCRAPE_JOB_RECONCILE_STALE은 오래된 포털 작업을 callback timeout으로 종료합니다.
• REFRESH_TOKEN_CLEANUP은 만료된 Refresh Token을 정리합니다.

Scheduler 리소스 정의는 이 저장소에 없습니다. 유지보수 작업이 실행되는지는 배포된 EventBridge Scheduler target과 Lambda invoke 권한을 확인해야 합니다.

Health와 API

curl -sS https://api.cchaksa.com/health
curl -sS https://api.cchaksa.com/actuator/health
curl -sS https://api.cchaksa.com/v3/api-docs

로그 상관관계

포털 장애는 jobId를 시작점으로 찾습니다. 다음 값을 함께 연결합니다.

• jobId.
• outboxId.
• queueMessageId.
• workerRequestId.
• operationType.

관측 도구의 역할

도구	우선 확인할 내용
GitHub Actions	Migration, Test, Build, Alias 변경
CloudWatch Logs	Lambda platform 로그와 stdout·stderr. prod file 로그 수집 여부는 외부 설정 확인
Sentry	예외 Stack Trace와 MDC tag
Grafana Cloud	활성화된 OTLP Metric과 외부 전달 로그. 현재 앱의 OTLP Trace exporter는 제외됨
PostgreSQL	작업·Outbox 상태와 학사 데이터 반영 결과

Grafana metric이나 Sentry event가 없다는 사실만으로 요청이 없었다고 단정하지 않습니다. 수집 설정과 Lambda 로그를 먼저 확인합니다.

prod Logback은 기본적으로 /var/log/app 파일과 Sentry에 기록하며 Console appender가 없습니다. Lambda에서 file 로그를 수집하려면 쓰기 가능한 LOG_PATH와 Telemetry Extension 또는 별도 전달 설정이 필요합니다. 해당 인프라 정의는 이 저장소에 없으므로 실제 Lambda 설정을 확인해야 합니다.