TDD(Test Driven Development)의 개념부터 Testcontainers가 왜 등장했는지 그리고 특정 버전과 호환되지 않아 발생하는 실제 문제와 해결 전략까지 정리해본다.

1️⃣ TDD(Test Driven Development)란?

TDD는 테스트를 먼저 작성하고 그 테스트를 통과하는 코드를 작성하는 개발 방식이다.

TDD의 기본 사이클 (Red → Green → Refactor)

1. Red
   • 실패하는 테스트를 먼저 작성
2. Green
   • 테스트를 통과시키는 최소한의 코드 작성
3. Refactor
   • 중복 제거, 구조 개선

2️⃣ TDD 장단점

✅ 장점

• 요구사항이 코드로 명확해진다 ⭐⭐⭐
• 회귀 버그 방지

❌ 단점

• 초기 개발 속도가 느리다
• 테스트 작성에 대한 러닝 커브 ⭐⭐
• 외부 의존성(DB, Redis, Kafka 등)이 많을수록 난이도 증가 ⭐⭐⭐

👉 이 지점에서 Testcontainers가 등장한다.

3️⃣ 기존 테스트 방식의 한계

보통 이런 방식으로 테스트를 작성해왔다.

• H2 같은 In-memory DB 사용
• 로컬 DB에 직접 의존
• *개발자마다 다른 환경 * ⭐⭐⭐

👉 운영 환경과 테스트 환경의 불일치가 가장 큰 문제다.

4️⃣ Testcontainers란?

Testcontainers는 테스트 코드에서 Docker 컨테이너를 직접 띄워 사용하는 라이브러리다.

핵심 개념

• 테스트 실행 시
  • 실제 DB / 메시지 브로커 / 인메모리 캐시 ... 등 컨테이너 실행 ⭐⭐
  • 테스트 종료 후 자동 정리
• 운영 환경과 동일한 버전 사용 가능

5️⃣ Testcontainers 기본 사용 예 (Spring Boot + JUnit + Java/Kotlin)

Gradle 의존성 및 Configuration

testImplementation("org.testcontainers:junit-jupiter")
testImplementation("org.testcontainers:mariadb")


-------------

@Testcontainers
@ActiveProfiles("test")
public abstract class TestContainerConfig {

    @Container
    protected static final MariaDBContainer<?> mariaDBContainer = new MariaDBContainer<>("mariadb:latest")
            .withDatabaseName(TestDBConfig.DB_NAME)
            .withUsername(TestDBConfig.USERNAME)
            .withPassword(TestDBConfig.PASSWORD);

    @DynamicPropertySource
    static void overrideProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", mariaDBContainer::getJdbcUrl);
        registry.add("spring.datasource.username", mariaDBContainer::getUsername);
        registry.add("spring.datasource.password", mariaDBContainer::getPassword);
    }
}

❗Testcontainers 문제 발생

Could not find a valid Docker environment. Please see logs and check configuration 라는 오류가 갑자기 잘되다가 발생

Caused by: java.lang.IllegalStateException: Could not find a valid Docker environment. Please see logs and check configuration
    at org.testcontainers.dockerclient.DockerClientProviderStrategy.lambda$getFirstValidStrategy$7(DockerClientProviderStrategy.java:274)
    at java.base/java.util.Optional.orElseThrow(Optional.java:403)
    at org.testcontainers.dockerclient.DockerClientProviderStrategy.getFirstValidStrategy(DockerClientProviderStrategy.java:265)

🚨 1. Docker CLI 버전 문제

❌ Docker 29.x 버전과 호환문제

✅ 해결 방법

• Docker Desktop 28.x 이하 버전 사용
• ** Spring Boot 3.5.8 이상으로 업그레이드 **
• ** docker.sock 경로 수정 **

  sudo ln -s $HOME/.docker/run/docker.sock /var/run/docker.sock

6️⃣ Testcontainers 장점

• 실제 DB 동작과 100% 동일 ⭐⭐
• CI/CD 환경에서도 재현 가능
• 로컬 환경 오염 없음 ⭐⭐⭐
• 테스트 간 독립성 보장 ⭐⭐⭐

7️⃣ 마무리

TDD를 도입하다가 포기하는 가장 큰 이유는 환경과 외부 의존성이다. Testcontainers는 이 문제를 거의 완벽하게 해결해 주지만 대신 버전 관리라는 새로운 책임을 요구한다. 잘 통제된 Testcontainers 환경은 테스트를 믿을 수 있게 만드는 마지막 퍼즐이라고 생각한다.

네이버 클라우드 백엔드 개발자 채용 과정에 참여하면서 경험한 내용을 정리했습니다.

*서류 → 기업문화적합도 검사 및 직무테스트 → 기술 면접 → 컬처 핏 및 레퍼체크 → 최종합격 * 순서로 진행되었습니다.

📌 지원 배경

• 지원 포지션: [NAVER Cloud] AI Voice Call 서비스 BE 개발 (경력)
• 지원 경력 조건 : 3년 이상

네이버 클라우드는 국내에서 드물게 대규모 트래픽 + 클라우드 네이티브 환경을 직접 경험할 수 있는 회사라고 생각했고 스타트업 회사를 다니면서 Iot 또는 웨어러블 디바이스 관련 소프트웨어를 개발에 대한 좋은기억이 있어 지원하게됨

🧾 서류 전형

• 결과: 합격
• 소요 기간: 2~3시간 이내

운이 좋게 합격을 했던것 같다. 서류는 참고로 "Naver Careers" 홈페이지를 통해 접수하면된다.

💻 기업문화적합도 검사

서류 전형 합격 이후, 기업문화적합도 검사를 진행하게 되었습니다.

• 기업문화적합도 검사는 두 가지 응답 방식이 섞여 있는 형태였습니다.

  1️⃣ 동의 정도 선택형

• 문항에 대해 전혀 그렇지 않다 ~ 매우 그렇다 (A~D) 중 하나를 선택
• 한 세트당 4개 문항에 응답

👉 일관성과 솔직함을 보는 느낌이 강했습니다.

2️⃣ 상대 비교 선택형

• 여러 문항 중 가장 나와 가까운 문항 1개 + 가장 먼 문항 1개 선택
• 한 세트당 2개 문항 선택

👉 단순히 좋게 답하는 것보다는 자기 성향을 명확히 드러내는 응답이 중요

⚠️ 응시 시 유의사항

• 정답이 있는 검사가 아니며 솔직한 응답이 가장 중요
• 응답이 불성실하거나 일관성이 없을 경우 결과가 무효 처리될 수 있다고 안내받음
• 조용한 환경에서 충분한 시간을 확보하고 응시하는 것을 권장
• 생각하면서 문항을 선택할 여유가 부족함

💻 온라인 직무 테스트(Codility)

기업문화적합도 검사 이후 온라인 직무 테스트(코딩 테스트) 안내 메일을 통해 테스트를 진행했습니다.

• 플랫폼: Codility
• 진행 방식: 온라인 코딩 테스트
• 응시 기한: 지정된 기간 내 자율 응시

📌 출제된 문제 유형

1️⃣ 토너먼트 방식의 게임 문제

• 시뮬레이션 기반 완전탐색

2️⃣ 팰린드롬 문제

• 주어진 문자열을 앞 뒤로 같은지 확인하여 팰린드롬 판별

3️⃣ 문자열 압축 최적화 문제

• 약간 야매..식 브루트포스 알고리즘으로 문제를 푼 기억 ( 너무 어려웠다 )

⚠️ 응시 시 유의사항

안내 메일에서 강조된 주의사항은 다음과 같았습니다.

• 타인의 도움, 웹 서핑, 코드 복사 금지
• 테스트 종료 전 문제 내용 공유 금지
• 시험 시작 후 중단 시 재응시 불가
• 기한 내 미응시 또는 최종 제출 미완료 시 불합격 처리
• 안정적인 인터넷 환경에서 응시 권장

👉 일반적인 코딩 테스트보다 부정행위 및 환경 조건에 대한 안내가 비교적 엄격한 편이었습니다.

✅ 준비하면서 느낀 점 & 팁

• 기업문화적합도 검사 유형이 낯설고 어색한 느낌이 많이 들고 시간이 상대적으로 부족 대답못하고 넘어간 경우도 생겼다.
• 코딩테스트 문제는 총 3문제 사고와 생각을 좀 많이 해야됨
• 평소에 알고리즘 문제를 안풀다보니 난이도가 상당히 높았다고 생각이 듬.

✍️ 마무리

비슷한 포지션을 준비하시는 분들께 조금이나마 도움이 되었으면 좋겠습니다 🙂

최근 AWS 비용을 점검하면서 DynamoDB의 청구 금액이 예상보다 높게 나오고 있다는 걸 확인했다. 특히 개발 환경(dev)과 운영 환경(prod) 모두에 동일한 방식으로 세팅되어 있어 불필요한 리소스 낭비가 있다고 문득 생각이듬. 이번 글에서는 제가 실제로 진행한 DynamoDB 비용 절감 여정을 공유하려고 합니다.

🧾 해결방안 탐색 및 해결

🪄 Step 1. Standard → Standard-IA 전환 (개발 환경)

먼저 개발 환경의 모든 테이블을 Standard → Standard-IA(Infrequent Access) 스토리지 클래스로 변경했습니다.

• Standard-IA 특징
  • 자주 접근하지 않는 데이터를 위해 설계
  • GB당 저장 비용은 저렴
  • 단 읽기/쓰기 요청이 많이 발생했을때 추가 비용 발생 가능성 높음

👉 dev 환경은 테스트 시에만 접근하므로 IA로 변경 시 읽기/쓰기 요청은 적지만 저장 데이터는 많기 때문에 확실히 유리했다.

🕒 Step 2. TTL + DynamoDB Streams + Firehose

다음은 오래된 데이터(Old Data) 정리 단계입니다. 데이터를 삭제하는 대신 추적 가능성을 유지하면서도 비용을 줄이는 방식을 택했습니다.

• TTL(Time To Live) 설정
• DynamoDB Streams 활성화
• Lambda → Firehose → S3 파이프라인 구축
  • Lambda : DynamoDB Stream [REMOVE] 이벤트 수신 후 Firehose로 JSON 전송
  • Firehose : JSON → Parquet 포맷 변환
  • S3(Data Lake) : 장기 보관용 저장소로 아카이빙 → Glue(Data Catalog) 구조화해서 Athena에서 SQL 조회도 가능

👉 삭제된 데이터도 로그 형태로 S3에 안전하게 보관

⚙️ Step 3. On-Demand → Provisioned 전환 (운영 환경)

운영 환경(prod)에서는 트래픽이 꾸준했기 때문에 온디맨드(On-Demand) 과금 방식이 오히려 비효율적이었습니다. 평균 RCU/WCU(읽기/쓰기 용량 단위)가 안정적으로 유지되는 상태라면 프로비저닝(Provisioned) 모드로 전환하는 것이 훨씬 저렴합니다.

• Before : On-demand (요청당 과금)
• After : Provisioned (고정 용량 + Auto Scaling)

👉 Auto Scaling도 같이 설정하여 트래픽 급증 시 자동으로 용량을 확장

💭 회고

솔직히 말하면 이번 프로젝트에서 DynamoDB에 대해 깊이 이해하지 못한 채 개발에만 집중해왔던 것 같다. 테이블 만들고 데이터 넣고 조회만 되면 “됐다”라고 생각했던것같다. 당시엔 “온디맨드(On-Demand) 방식이면 내가 쓴 만큼만 요금이 나오겠지” 라고 단순하게 생각했다. 하지만 청구서를 보고 많은걸 느꼈던것같다. 이번 비용 절감 작업을 하면서 느꼈던 건 운영 효율도 결국 개발의 일부고 단순히 코드만 잘 짜는게 아니라 서비스의 동작 원리와 과금 구조를 이해하는것이 진짜 백엔드 개발자의 완성이라는 걸 새삼 깨달았다.

Amazon Q Developer는 개발자를 위한 AI 대화형 비서로 AWS 리소스 관리, 문서 검색, 코드 생성, 인프라 구성까지 VS Code 안에서 대화형으로 수행할 수 있습니다.

🧩 1. VS Code 설치

Amazon Q Developer는 VS Code 확장(Extension) 형태로 동작합니다.

• Visual Studio Code 다운로드
• 운영체제(Windows, macOS, Linux)에 맞게 설치

설치 후 실행하면 Amazon Q Extension 을 추가할 수 있습니다.
(Extensions → Amazon Q 검색)

⚙️ 2. uvx 설치 (Windows 환경)

Amazon Q Developer의 MCP 서버를 설치하려면 Python 패키지 관리자 uvx가 필요합니다.

🪟 PowerShell 실행 정책 설정

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

📦 uv 설치

-ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

✅ 설치 확인

uv --version

🔑 3. Amazon Credential 설정 (MSI 설치 방식)

Amazon Q Developer는 AWS 계정 권한을 이용해 AWS 모든 리소스를 직접 다룹니다.

3-1. AWS CLI v2 다운로드 및 설치

• AWS CLI v2 (Windows MSI)
• 다운로드 → 설치 진행

3-2. 설치 확인

aws --version

*예시 출력: *aws-cli/2.15.30 Python/3.11.7 Windows/10 exe/AMD64 prompt/off

3-3. AWS 자격 증명 설정

aws configure

• 입력 항목

• AWS Access Key ID
• AWS Secret Access Key
• Default region name
• Output format

🧠 4. MCP 서버 설치

Amazon Q Developer는 MCP (Model Context Protocol) 을 기반으로 AWS API, 문서, 지식베이스에 접근합니다. 각 MCP 서버는 AI에게 AWS 리소스 컨텍스트를 제공합니다.

4-1. AWS Documentation MCP Server

• AWS 공식 문서를 직접 참조할 수 있게 하는 MCP 서버
• 참고 링크

  4-2. AWS API MCP Server

• AWS API 호출 정보 (예: EC2, Lambda 등) 에 접근할 수 있게 하는 서버
• 참고 링크

  4-3. AWS Knowledge MCP Server

• AWS 내부 기술 문서, 아키텍처 가이드, FAQ 지식 베이스 등을 조회할 수 있게 해주는 MCP 서버
• 참고 링크

🚀 5. Amazon Q Developer 실전 사용 결과

Q. DynamoDB에서 비용이 많이 발생되는것 같은데 비용 발생 원인 파악과 해결방안

A. 분석 → 원인 → 해결 → 절감 효과

✅ AI를 기반으로 클라우드 환경 구축 가능하다.

✅ AWS 리소스 관리, 코드 생성, 인프라 자동화를 대화형으로 통합할 수 있다.

✅ Spring Boot + AWS + Terraform 환경에서 IaC(Infrastructure as Code)를 자주 다루는 개발자에게 강력한 생산성 향상을 제공

현대의 소프트웨어는 단순 CRUD를 넘어서 복잡한 도메인 로직과 높은 확장성 요구를 동시에 만족해야 합니다.
이 과정에서 자주 등장하는 개념이 바로 DDD, 에그리거트(Aggregate), 바운디드 컨텍스트(Bounded Context), CQRS, 이벤트 소싱(Event Sourcing) 입니다.

이 글에서는 이 다섯 가지 개념이 어떻게 연결되는지 큰 그림과 흐름을 다루도록 하겠습니다.

📖 1. DDD (Domain-Driven Design)

DDD의 핵심은 도메인 전문가와 개발자가 같은 언어(유비쿼터스 언어)를 사용하여 소프트웨어를 설계하는 것입니다.
단순한 데이터 중심 설계가 아니라 도메인 로직 중심으로 모델을 만들고, 코드와 비즈니스 개념이 일치하도록 하는 것이 목표입니다.

DDD의 주요 개념:

• 유비쿼터스 언어: 도메인 전문가와 개발자가 공유하는 용어 체계
• 바운디드 컨텍스트: 모델의 경계를 명확히 하여 혼란 방지
• 에그리거트: 경계 내부의 일관성을 유지하는 단위

📖 2. 바운디드 컨텍스트 (Bounded Context)

현실 세계의 비즈니스는 크고 복잡합니다. 예를 들어 "회원(Member)"이라는 단어도 결제 시스템에서는 "고객(Customer)" 인사 시스템에서는 "직원(Employee)" 으로 다르게 쓰일 수 있습니다.

이를 해결하는 방법이 바운디드 컨텍스트입니다.

• 각 컨텍스트는 자체적인 모델과 의미를 가집니다.
• 서로 다른 컨텍스트는 명시적인 인터페이스(API, 이벤트)로 통신합니다.
• 결과적으로 경계를 명확히 나눔으로써 모델의 혼란과 충돌을 줄입니다.

예시)

            [ 비즈니스 전체 도메인 ]
                  ┌──────────────┐
                  │   회사 운영   │
                  └──────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                                      │
 ┌─────────────┐                       ┌───────────────┐
   결제 시스템                            인사 시스템 
   Payment BC                               HR BC     
 └─────────────┘                       └───────────────┘
        │                                      │
 ┌───────────────┐                       ┌───────────────┐
     Customer                               Employee     
      (고객)                                  (직원)       
    - 이름                                  - 이름        
    - 결제수단                              - 부서        
    - 구매내역                              - 급여        
 └───────────────┘                       └───────────────┘
        │                                      │
        └──────────── 명시적 인터페이스(API/이벤트

📖 3. 에그리거트 (Aggregate)

바운디드 컨텍스트 내부에서도 모든 객체가 뒤엉켜 있으면 유지보수가 어렵습니다.
그래서 일관성 경계(Consistency Boundary)를 정하고 그 안에서 항상 규칙이 지켜지도록 하는 단위가 에그리거트입니다.

• Aggregate Root: 외부에서 접근 가능한 유일한 진입점
• 내부 엔티티(Value Object 포함): Root를 통해서만 접근/수정 가능

예시)

• Order (Root) + OrderItem (내부 엔티티)
• Post (Root) + Comment (내부 엔티티)
• Account (Root) + Transaction (내부 엔티티)

👉 핵심은 트랜잭션은 Aggregate 단위로 보장된다는 점입니다.

📖 4. CQRS (Command Query Responsibility Segregation)

일반적으로 하나의 모델로 읽기와 쓰기를 동시에 처리합니다.
하지만 트래픽이 커지고 복잡도가 올라가면 쓰기(Command)와 읽기(Query)를 분리하는 CQRS 패턴이 등장합니다.

• Command 모델: 상태 변경 담당 (도메인 규칙, 트랜잭션)
• Query 모델: 데이터 조회 담당 (성능 최적화, 캐싱, 별도 저장소)

장점:

• 읽기와 쓰기를 따로 확장 가능
• 복잡한 도메인 로직과 단순 조회 로직 분리

단점:

• 결국 Eventual Consistency(최종적 일관성) 문제를 다뤄야 함
• 단순 CRUD 시스템에는 과도한 설계

예시)

UserRepository는 쓰기용 DB(JPA 기반)
UserReadRepository는 읽기용 DB(캐시 or 조회 전용 DB)로 나눌 수 있다.

📖 5. 이벤트 소싱 (Event Sourcing)

일반적으로 DB에는 "현재 상태"만 저장합니다.
이벤트 소싱은 다른 접근을 택합니다. 상태 변화를 만든 모든 이벤트를 저장합니다.

장점:

• 모든 변경 이력을 100% 보존 (추적 용이)
• 원하는 시점의 상태 복원 가능
• 이벤트를 다른 시스템에 쉽게 전달 가능 (이벤트 드리븐 아키텍처)

단점:

• 이벤트가 많아지면 리플레이 비용 발생 → 스냅샷 필요
• 이벤트 스키마 진화 관리 어려움

예시)

사용자가 주문을 생성/결제/취소하는 과정을 이벤트로 저장

📖 6. 개념들의 연결

이 다섯 가지 개념은 따로 노는 것이 아니라 하나의 스토리를 이룹니다.

• DDD: 복잡한 도메인을 다루기 위한 철학
• 바운디드 컨텍스트: 모델의 경계를 나누는 방법
• 에그리거트: 경계 내부의 일관성을 지키는 단위
• CQRS: 확장성을 위한 읽기/쓰기 분리
• 이벤트 소싱: CQRS와 잘 어울리는 상태 관리 방식

DDD → BC → Aggregate → CQRS → Event Sourcing 이런 흐름으로 연결됩니다.

📖 7. 언제 쓰면 좋을까?

• 단순한 CRUD 서비스 → 필요 없음 (오버엔지니어링)
• 복잡한 비즈니스 규칙 + 높은 확장성 요구 → 적합
• *금융, 이커머스, 로깅/추적 시스템 → 이벤트 소싱 + CQRS 강력 추천 *

📖 8. 마무리

모두 복잡한 도메인을 효과적으로 다루기 위한 도구입니다.
하지만 "무조건 쓰는 패턴"이 아니라 도메인 특성과 요구사항에 맞춰 선택적으로 적용해야 합니다.

혹시 궁금한 부분이나 더 보고 싶은 주제가 있다면 댓글로 남겨주세요 🙌

백엔드 API를 개발하다 보면 프론트엔드/QA 팀과 API 명세를 문서로 공유하는 일이 필수적입니다.
과거에는 Excel이나 Wiki에 수동으로 작성했지만, 이제는 Swagger(OpenAPI) 를 통해 API 문서를 자동으로 생성하고 유지보수할 수 있습니다.

이번 글에서는 Spring Boot 3.4 + Java 21 + Gradle 환경을 기준으로, Swagger를 적용하고 운영할 때의 Best Practice를 소개합니다.

🔧 1. 의존성 추가

build.gradle에 OpenAPI 관련 의존성을 추가합니다.
Spring Boot 3에서는 springdoc-openapi 라이브러리가 가장 많이 사용됩니다.

dependencies {
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'
}

📌 2. Swagger UI 접근 방법

의존성만 추가하면 자동으로 Swagger UI 가 활성화됩니다.

기본 경로: http://{{호스트}}:{{포트}}/swagger-ui.html

OpenAPI 문서(JSON): http://{{호스트}}:{{포트}}/v1/api-docs

회사 내 보안 정책에 따라 접근 권한을 제어하거나, 프로필별로 설정을 분리하는 것이 중요합니다.

⚙️ 3. Swagger 설정 커스터마이징

/**
 * Swagger UI 상단에 표시되는 API 정보가 이 부분에서 설정
 */
@Configuration
@OpenAPIDefinition(
        info = @Info(
                title = "테스트 전용 API",
                description = "개인적으로 테스트하기 위한 API 문서입니다",
                version = "v1"
        )
)
public class SwaggerConfiguration {

}



/**
 * Swagger 화면에서 사용자 편의성을 높이는 옵션
 * Swagger UI에서 사용자/관리자 API를 탭으로 구분
 */

springdoc:
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  api-docs:
    path: /v1/api-docs
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: alpha
    tags-sorter: alpha
    display-query-params-without-oauth2: true
    disable-swagger-default-url: true
    doc-expansion: list
    defaultModelsExpandDepth: 1
    defaultModelExpandDepth: 2
    defaultModelRendering: model
    show-extensions: true
    show-common-extensions: true
    display-request-duration: true
    try-it-out-enabled: true
  group-configs:
    - group: 사용자
      paths-to-match:
        - /v1/member/**
        - /v1/board/**
    - group: 관리자
      paths-to-match:
        - /v1/admin/**

🛠 4. Controller 예제

/**
 * 사용자 생성 API
 */
    @Operation(
            summary = "사용자 생성",
            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
                    required = true,
                    content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = CreateMemberRequest.class)
                    )
            ),
            responses = {
                    @ApiResponse(
                            responseCode = "201",
                            description = "사용자 생성 완료",
                            content = {
                                    @Content(
                                            mediaType = "application/json",
                                            schema = @Schema(implementation = CommonResponse.class)
                                    ),
                            }
                    ),
            }
    )
    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public CommonResponse createMember(@Valid @RequestBody CreateMemberRequest createMemberRequest) {
        Member member = memberWebMapper.toDomain(createMemberRequest);
        Member resultMember = createMemberUseCase.createMember(member);
        CreateMemberResponse createMemberResponse = memberWebMapper.toCreateMemberResponse(resultMember);
        CommonResponse commonResponse = new CommonResponse<>("사용자 생성이 정상적으로 처리됐습니다", createMemberResponse);
        return commonResponse;
    }

👉 5. 활용 사례

• 백엔드(Spring Boot) → /v1/api-docs 제공
• 프론트엔드 → OpenAPI Generator, orval, swagger-typescript-api 등을 활용하여
  • 타입 정의
  • API 호출 코드
  • React Query/SWR 훅 자동으로 생성 가능

🎯 6. 마무리

Swagger(OpenAPI)는 API 개발/운영에서 협업 효율을 극대화하는 도구입니다.
Spring Boot에서는 springdoc-openapi를 통해 쉽게 적용할 수 있고,
보안/프로필 분리/문서 관리까지 신경쓴다면 실무에 바로 적용 가능한 베스트 프랙티스가 됩니다.

"도메인 로직을 외부 의존성으로부터 격리하여 더 유연하고 테스트 가능한 애플리케이션을 만든다!"

• 예시

  • UserService가 곧바로 JPA Repository와 EmailClient에 의존

    @Service
    public class UserService {
    
    private final UserRepository userRepository; // JPA Repository
    private final EmailClient emailClient;       // 외부 Email API
    
    

...

}

---

## ⚡ 핵심 개념
- 🧩 **Domain (코어 비즈니스 로직)**
- 🔌 **Ports (인터페이스, 추상화)**
- 🔄 **Adapters (외부 연동: DB, API, 메시징 등)**

---


### 📊 아키텍처 비교

| 구조 | 특징 | 문제점 |
|------|------|--------|
| 🏗️ Layered | Controller → Service → Repository | 외부 의존성(DB, 외부 API)에 강하게 묶임 |
| 🔷 Hexagonal | Domain 중심, Ports & Adapters | 외부 교체 용이, 테스트 용이 |
---

### 🗂️ 실제 나의 토이 프로젝트 레이어 구조 (예시)

📦 user Bounded Context (User 도메인 전체 경계) ┣ 📂 adapter Adapter Layer (외부 세계와 연결 지점) ┃ ┣ 📂 in Inbound Adapter (들어오는 요청 처리) ┃ ┃ ┗ 📂 web REST API Controller, Request/Response DTO ┃ ┗ 📂 out Outbound Adapter (외부 자원 연동) ┃ ┗ 📂 persistence JPA Entity, Repository, Mapper (DB 연동) ┣ 📂 application Application Layer (유즈케이스 중심) ┃ ┣ 📂 port Port (도메인 ↔ Adapter 느슨한 연결/계약) ┃ ┃ ┣ 📂 in Inbound Port (UseCase 인터페이스) ┃ ┃ ┗ 📂 out Outbound Port (Persistence 인터페이스) ┃ ┗ 📂 service Application Service (유즈케이스 구현체) ┗ 📂 domain Domain Layer (핵심 비즈니스 모델/로직)

---

## 💡 정리 & 회고
- ✅ 장점: 테스트 용이, 도메인 로직의 독립성 확보
- ⚠️ 단점: 구조가 복잡함. 소규모 프로젝트에는 과한 느낌
- 🧭 개인적으로는 중장기 유지보수 프로젝트에서 큰 힘이 됨

제품을 기획하고 개발할 때, "무엇을", "왜", "어떻게 만들 것인가"에 대한 방향성을 명확히 하기 위해 작성하는 문서가 PRD 입니다.

🤔 개발이 시작되기 전까지 우리는 종종 다음과 같은 질문을 받거나 합니다.

• 이 기능은 왜 필요한가요?
• 어떤 유저를 위한 기능인가요?
• 어떤 상황에서 어떤 조건으로 동작하나요?

이 질문들에 대한 공통된 답을 팀 전체가 할 수 있도록 해주는 것이 바로 PRD 입니다.

🧩 PRD의 핵심 구성 요소

아래는 대부분의 조직에서 공통적으로 사용하는 PRD 기본 구성입니다. 상황에 따라 유연하게 커스터마이징할 수 있습니다.

1. ✨ 목표(Goal)

• 이 문서를 작성하는 목적과 해당 기능/제품이 기여할 비즈니스 목표
  • 예 : "GPS를 기반으로 사용자의 위치에 따른 지역 날씨정보를 실시간으로 제공해줌으로써 편의성을 제공"

2. 👤 대상 사용자(User Persona)

• 주요 사용자 유형과 어떤 문제를 겪고 있는지 그리고 어떤 가치를 제공할 것인지
  • 예 : "출퇴근 직장인, 학부모, 학생, 러너"

3. 📚 배경(Background & Context)

• 기존의 문제 상황 또는 시장 조사나 데이터 기반 인사이트
  • 예 : 사내 VOC 분석 및 사용자 설문 결과에서도 “실제 느낌을 반영한 날씨 정보가 부족하다”는 피드백 다수 존재

4. 📌 요구사항(Requirements)

기능적 요구사항

• 유저 플로우 (시나리오 기반)
  • 예 : "사용자는 Kakao 또는 Google 계정을 통해 로그인할 수 있어야 한다."

비기능적 요구사항

• 성능, 보안, 확장성 등
  • 예 : "로그인 응답 시간은 200ms 이내 여야한다."

5. ✅ 성공 기준(Success Metrics)

• 이 기능이 성공했다고 말할 수 있는 기준
  • 예 : " DAU 증가, 전환율 개선, 사용자 만족도"

6. 🔄 스코프 정의

• 포함 범위 (In Scope)
  • 예 : "이번 스프린트에서는 OOO까지가 in-scope 입니다."
• 제외 범위 (Out of Scope)
  • 예 : "해당 기능은 out-of-scope 이지만 다음 사이클에서 다룰 예정입니다."

7. 🎨 와이어프레임 / UX 흐름(Optional)

• 기본적인 화면 구조
• 인터랙션 애니메이션
• 스크린 플로우

💡 실무에서의 PRD 작성 팁

• 모호함은 줄이고 구체적으로 작성하기
• 개발자, 디자이너, PM 모두를 위한 문서이기 때문에 기술적, 기획적, 디자인 관점에서 누구나 이해할 수 있어야 한다.
• PRD는 살아있는 문서이기때문에 항상 최신 업데이트하기

🙋 PRD는 왜 중요한가?

🧠 마무리

PRD는 단순한 기획 문서가 아닙니다. 개발자와 디자이너, 기획자, 심지어 마케팅팀까지 같은 이해를 공유하도록 도와주는 소통의 도구 이다.

💻 WebClient

• Spring Boot에서 제공하는 고수준(High-level) 비동기·논블로킹 기반 HTTP 클라이언트
• Spring WebFlux 기반
• 응답 모델 자동 역직렬화 (Jackson 등)
• 메소드 체이닝 방식

📡 HttpClient

• 저수준(Low-level) 비동기 HTTP 클라이언트
• Reactor-Netty 기반
• 응답은 ByteBuf/ByteBuffer 형태로 제공 → JSON은 직접 파싱 필요
• 커넥션 풀, 타임아웃, SSL 등 세부 튜닝 가능

🧩 ReactorClientHttpConnector

• WebClient와 HttpClient를 연결하는 어댑터/브리지 역할
• HttpClient에서 세부 설정한 후, 이를 WebClient에 주입

2️⃣ 주요 차이점

3️⃣ 장단점

💻 WebClient

장점 ✅

• 자동 직렬화/역직렬화
• 필터, 리트라이, 백프레셔 등 리액티브 패턴 쉽게 구현
• 코드 간결

단점 ⚠️

• 세부 네트워크 설정은 HttpClient 의존
• 리액티브 프로그래밍 러닝 커브 존재

📡 HttpClient

장점 ✅

• 세부 네트워크 설정 가능(ConnectionProvider, 타임아웃, TLS, 프록시 등)
• 대규모 트래픽·특수 프로토콜에 대응 가능

단점 ⚠️

• JSON 파싱, 에러 처리, 리트라이 직접 구현 필요
• 코드 복잡도 증가

4️⃣ HttpClient + WebClient & ReactorClientHttpConnector 실전 예시

    /**
     * 공통 커넥션 풀 설정 (커넥션 재사용을 위함)
     */
    @Bean
    public ConnectionProvider connectionProvider() {
        return ConnectionProvider.builder("test-pool")
                .maxConnections(100)
                .pendingAcquireMaxCount(500)
                .pendingAcquireTimeout(Duration.ofSeconds(30))
                .build();
    }




    /**
     * Webclient 정의 (ReactorClientHttpConnector 활용하여
     */
    @Bean
    public HttpClient createHttpClient(ConnectionProvider connectionProvider) {

        SslContext sslContext;
        try {
            sslContext = SslContextBuilder.forClient().build();
        } catch (SSLException e) {
            throw new CustomRuntimeException(ErrorEnum.SSL_CONTEXT_ERROR);
        }
        return HttpClient.create(connectionProvider)
                .secure(sslContextSpec -> sslContextSpec.sslContext(sslContext).handshakeTimeout(Duration.ofSeconds(30)))
                .responseTimeout(Duration.ofSeconds(90))
                .doOnConnected(conn -> conn
                        .addHandlerLast(new ReadTimeoutHandler(90))
                        .addHandlerLast(new WriteTimeoutHandler(5)));

    }    



    /**
     * 공통 HttpClient (응답 타임아웃 설정 포함)
     */    
    @Bean
    public WebClient testWebClient(HttpClient httpClient) {

        DefaultUriBuilderFactory factory = new DefaultUriBuilderFactory("https://example.com/test");
        factory.setEncodingMode(DefaultUriBuilderFactory.EncodingMode.VALUES_ONLY);

        //WebClient 기본 버퍼가 256KB 때문에 초과하면 BufferLimitException 발생
        return WebClient.builder()
                .clientConnector(new ReactorClientHttpConnector(httpClient))
                .uriBuilderFactory(factory)
                .baseUrl("https://example.com/test")
                .exchangeStrategies(ExchangeStrategies.builder()
                        .codecs(configurer -> configurer
                                .defaultCodecs()
                                .maxInMemorySize(10 * 1024 * 1024)) // ✅ 최대 10MB
                        .build())
                .build();
    }

5️⃣ Mono 기반의 비동기·논블로킹 호출

@Component
@RequiredArgsConstructor
public class TestProvider {


    private final WebClient testWebClient;


    /**
     * Mono 활용한 비동기 호출
     */
    private Mono<TestDTO> test() {

        return testWebClient.get()
                .uri(uriBuilder -> uriBuilder
                        .queryParam("serviceKey", "testKey")
                        .queryParam("pageNo", 1)
                        .queryParam("numOfRows", 1000)
                        .queryParam("returnType", "JSON")
                        .build())
                .retrieve()
                .bodyToMono(TestDTO.class)
                .doOnError(TimeoutException.class, e -> log.error("⏳ TimeoutException 발생 : {}", e.getMessage()))
                .doOnError(IllegalStateException.class, e -> log.error("⏳ IllegalStateException 발생 : {}", e.getMessage()))
                .doOnError(WebClientResponseException.class, e -> log.error("⏳ WebClientResponseException 발생 : {}", e.getMessage()))
                .retryWhen(Retry.fixedDelay(5, Duration.ofSeconds(5))
                        .filter(throwable -> throwable instanceof TimeoutException || throwable instanceof IllegalStateException || throwable instanceof WebClientResponseException)
                        .doBeforeRetry(retrySignal -> {
                            Throwable failure = retrySignal.failure();
                            log.warn("🔁 [ 테스트 서드파티  {}회차 재시도] 이유: {}",
                                    retrySignal.totalRetries() + 1,
                                    failure.getMessage());
                        }));
    }
}

결론 🎯

• 일반적인 REST API 호출 → WebClient 단독 사용
• 세밀한 네트워크 제어 필요 시 → HttpClient 설정 후 ReactorClientHttpConnector로 WebClient에 주입

코드 리뷰가 없다는 것은 그 누구도 내 코드에 책임지지 않는다는 뜻일수도 있다고 생각했다.

❗ 그 순간의 깨달음

• 코드리뷰가 존재하지 않는 조직은 빠른 구현만을 미덕으로 여기는 경향이 있음
• 품질, 안정성은 논의조차 되지 않았음
• 코드에 대한 집단적 신뢰 구조가 부재

2. 🔥 장애에 대한 무감각한 대응

시스템보다 문제를 대하는 조직의 태도가 더 무서웠다.

• 충분하지 않은 회귀테스트 및 엣지 테스트 진행, 테스트 코드 미작성 → 애플리케이션 장애 발생
• 장애 후 팀의 회고 : "장애가 되는 부분을 어떻게 해결할지 보다는 서비스에서 빼는 방향으로 생각"

⚠ 조직의 대응 방식

• 근본 원인 분석 없음
• 재발 방지 대책 없음
• “장애에 대해서 해결방안을 제시하거나 생각하기보다는 제거한다”는 임시 방편만 남음

3. 🧱 변화에 둔감한 조직, 무력한 개인

“지금 잘 돌아가는데 왜 고치냐”는 말은 성장을 가로막는 가장 단단한 벽이었다.

• 언제 터질지 모르는 시한폭탄
• 레거시 코드를 리팩토링 하려는 자세가 안보임
• 새로운 기술 제안도 "우린 그거 안 써봤어 또는 두려움"
• 변화에 둔감한 조직에서 도전은 유난으로 취급됨

😞 자존감을 갉아먹는 환경

• 성장이 불가능한 토양 위에 서 있었음
• 이것은 건강한 책임감이 아닌 조직이 만든 가스라이팅

4. 🧭 오너십과 문제 중심 성장에 대한 생각

오너십은 열정과 책임을 요구한다기보다 문제 중심의 성장을 위해 시야를 넓혀주는 말이라고 생각한다.

• 업무를 ‘내 일’처럼 생각하고 주도적으로 접근하는 태도
• 단순한 ‘시키는 일’ 수행이 아니라 전체 맥락 속 역할을 이해하려는 자세

🧠 오너십을 기르는 방법

• 스스로 "왜 이 작업이 필요한가?"를 생각하고 정의해보기
• 전체 업무 흐름 속에서 내가 맡은 작업의 위치와 맥락 이해하기
• 작업을 진행하기 전/후로 사용자 입장에서 시나리오를 상상해보기
• 문제가 발생했을 때 기술적 수정에 그치지 않고 본질을 되짚어보기

5. ❓ '왜'를 묻는 습관

'왜?'라는 질문은 단순한 호기심이 아닌 업무 맥락을 더 깊게 이해하려는 시도다.

• 왜 이 기능이 필요한가?
• 왜 이 방식으로 구현해야 하는가?
• 왜 지금 이 시점에서 이 기능을 진행하는가?

⚠ '왜'를 묻지 않는 개발자의 특징

• 시킨 일만 수행
• 문서만 보고 구현
• 피드백 오면 고치고 끝
• 팀원들과 소통 없이 개인 단위로 개발

6. 🧩 기술보다 맥락을 먼저 이해하는 개발자

기술 중심 사고보다 문제 중심 사고가 우선이다.

• 문제 정의와 문제를 어떻게 해결할지 방법을 생각하면서 기술을 선택하는 자세가 필요함
• 기술 선택은 개인의 흥미나 유행이 아니라 문제를 해결하기 위한 맥락과 필요에 따른 결정이어야 한다.

7. 🌱 성장에 대한 관점

성장은 어느 날 갑자기 오지 않는다.

• 별것 아닌 듯 지나쳤던 요소 하나하나를 주의 깊게 바라보기 시작할 때
• 작은 의문과 고민들이 쌓여 진짜 성장으로 이어진다.

📝 한 줄 결론

좋은 개발자는 “비즈니스 문제를 정확히 인식하고 그 해결을 위한 코드를 고민하고 조직과 커뮤니케이션하며 함께 성장하는 사람”이다.

MapStruct로 빠르고 깔끔하게 매핑 자동화하기!

📌 MapStruct란?

MapStruct는 Java Bean 간의 매핑 코드를 컴파일 타임에 자동 생성해주는 객체 매핑 라이브러리입니다.
Lombok처럼 Annotation 기반으로 정의하면, @Mapper 인터페이스 구현체를 자동으로 만들어줍니다.

✔️ 수동 매핑에서 해방되고, 성능도 뛰어난 객체 매퍼입니다.

✅ MapStruct의 주요 특징

• 컴파일 타임 생성: 리플렉션을 사용하지 않아 성능이 빠름
• 타입 안정성: 컴파일 오류로 잘못된 매핑을 사전에 방지
• 간결한 코드: 반복적인 매핑 로직 제거
• 커스터마이징 가능: 커스텀 매핑, 조건부 매핑 등 유연한 설정 지원

🌟 MapStruct의 장점

⚠️ MapStruct의 단점

🛠️ 실무 적용 예시

아래는 실무에서 사용한 MapStruct 기반 DTO ↔ Entity 매핑 예시입니다.

// com.example.demo.member.adapter.in.web


@Mapper(componentModel = "spring")
public interface MemberWebMapper {

    Member toDomain(CreateMemberRequest createMemberRequest);

    CreateMemberResponse toCreateMemberResponse(Member member);

    GetMemberResponse toGetMemberResponse(Member member);

    default Member toDomain(String memberId) {
        return Member.builder()
                .id(memberId)
                .build();
    }
}

// com.example.demo.member.adapter.out.persistence


@Mapper(componentModel = "spring")
public interface MemberPersistenceMapper {

    MemberJpaEntity toJpaEntity(Member member);

    Member toDomain(MemberJpaEntity memberJpaEntity);

}

📂 헥사고날 아키텍처 기반 책임분리

Persistence 영역과 사용자 useCase영역을 분리 이후 MapStruct 사용

🧪 테스트 코드 예시

@DisplayName("Member Domain Unit Test")
public class MemberTest {

    private final MemberWebMapper mapper = new MemberWebMapperImpl();

    @Test
    void 회원_정상_생성_요청에서_도메인_변환() {
        // given
        CreateMemberRequest request = new CreateMemberRequest(
                "user@example.com",
                "QWERasdf1234!",
                "홍길동",
                GenderEnum.MALE,
                "010-1234-5678",
                "서울특별시 강남구 테헤란로 123"
        );

        // when
        Member member = mapper.toDomain(request);

        // then
        assertAll(
                () -> assertEquals("user@example.com", member.getEmail()),
                () -> assertEquals("QWERasdf1234!", member.getPassword()),
                () -> assertEquals("홍길동", member.getName()),
                () -> assertEquals(GenderEnum.MALE, member.getGender()),
                () -> assertEquals("010-1234-5678", member.getPhoneNumber()),
                () -> assertEquals("서울특별시 강남구 테헤란로 123", member.getAddress())
        );

    }
}

📚 마무리

MapStruct는 반복적인 DTO ↔ Entity 매핑 코드를 컴파일 타임에 자동으로 생성해줌으로써
개발자의 생산성을 높이고, 코드의 안정성과 유지보수성을 동시에 잡을 수 있는 훌륭한 도구입니다. 특히 Spring Boot와 결합하면 @Mapper(componentModel = "spring") 설정 하나로 DI까지 연동되기 때문에
복잡한 변환 로직 없이 깔끔하고 명확한 코드 구조를 유지할 수 있습니다.

Flyway는 데이터베이스 스키마의 변경사항을 버전 관리할 수 있게 도와주는 오픈소스 마이그레이션 도구입니다.
SQL 파일 또는 Java 코드를 통해 마이그레이션을 정의하고, 프로젝트 빌드 또는 실행 시 자동으로 DB 변경을 적용할 수 있습니다.

✔️ SQL도 Git처럼 버전 관리해보자
✔️ 즉, DB를 코드처럼 관리할 수 있게 해줍니다.

✅ Flyway의 주요 특징

• 버전 기반의 마이그레이션 관리 (V1__init.sql, V2__add_table.sql)
• 자동 적용: Spring Boot 실행 시 마이그레이션 자동 수행
• 검증 기능: 마이그레이션 파일 변경 여부 탐지 및 무결성 검사
• 다양한 DB 지원: MySQL, PostgreSQL, Oracle, MSSQL, H2 등 대부분 지원
• SQL 또는 Java 코드 기반 작성 가능

🌟 Flyway의 장점

⚠️ Flyway의 단점

🛠️ Spring Boot + Flyway 실전 적용기

1. Gradle 의존성 추가

dependencies {
        implementation 'org.flywaydb:flyway-core'
        implementation 'org.flywaydb:flyway-mysql'
}

2. application.yml 설정

spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    validate-on-migrate: true

3. 마이그레이션 파일 작성

-- src/main/resources/db/migration/V1__create_member_table.sql

CREATE TABLE member
(
    id           VARCHAR(26)  NOT NULL PRIMARY KEY COMMENT 'ULID 기반 식별자',
    email        VARCHAR(254) NOT NULL COMMENT '이메일 (RFC 5321 표준)',
    password     VARCHAR(128) NOT NULL COMMENT '비밀번호',
    name         VARCHAR(50)  NOT NULL COMMENT '회원 이름',
    gender       VARCHAR(10)  NOT NULL COMMENT '성별',
    phone_number VARCHAR(20)  NOT NULL COMMENT '전화번호',
    address      VARCHAR(200) NOT NULL COMMENT '주소',
    is_deleted   TINYINT(1)   NOT NULL COMMENT '삭제 유무',
    deleted_at   DATETIME     NULL COMMENT '삭제 일시',
    created_at   DATETIME     NOT NULL COMMENT '생성 일시',
    updated_at   DATETIME     NOT NULL COMMENT '수정 일시',


    CONSTRAINT chk_gender CHECK (gender IN ('MALE', 'FEMALE'))
);

-- src/main/resources/db/migration/V2__add_email_to_user.sql


ALTER TABLE member ADD CONSTRAINT uq_member_email UNIQUE (email);

4. 실행 시 로그 확인

2025-07-24T18:40:04.281+09:00  INFO 27328 --- [  restartedMain] org.flywaydb.core.FlywayExecutor         : Database: jdbc:mariadb://localhost/local?user=localUser&password=********&serverTimezone=Asia/Seoul (MariaDB 11.7)
2025-07-24T18:40:04.302+09:00  WARN 27328 --- [  restartedMain] o.f.c.internal.database.base.Database    : Flyway upgrade recommended: MariaDB 11.7 is newer than this version of Flyway and support has not been tested. The latest supported version of MariaDB is 11.2.

📂 Flyway 마이그레이션 파일명 규칙

Flyway는 마이그레이션 파일명을 통해 버전과 설명을 파악하고, 순서에 따라 실행합니다.

파일명 규칙: V{버전}__{설명}.sql (밑줄 2개)

📚 마무리

Flyway는 DB 변경 사항을 안전하게 추적하고 자동화할 수 있는 강력한 도구입니다. 수동 SQL 관리로 인한 혼선을 줄이고, 팀원 간의 협업 효율도 높일 수 있습니다.

이전글에서 Docker Compose를 활용하여 Loki + Prometheus 구축하는 글을 보고 오는걸 참고하길 바란다.

https://velog.io/@dev-hsl-960221/Docker-Compose%EB%A5%BC-%ED%99%9C%EC%9A%A9%ED%95%9C-PrometheusLokiGrafana-%EA%B5%AC%EC%B6%95-%EB%B0%8F-%EC%84%9C%EB%B9%84%EC%8A%A4-%EC%9A%B4%EC%98%81

1️⃣ Grafana + Prometheus 연동

호스트주소가 아닌 prometheus 키워드로 사용❓

※ Docker Compose에서 여러 서비스를 정의할 때, 같은 네트워크에 속한 컨테이너끼리는 서비스 이름으로 서로를 호출할 수 있습니다.

2️⃣ 대시보드 생성

3️⃣ 대시보드 셋팅

✅ 앱 서비스들에 대한 환경변수를 job으로 설정 ※ 여기서 말하는 앱 서비스들은 ECS FARGATE 환경으로 구성된 TASK(POD)임 ECS 서비스 내 기능중에서 서비스 디스커버리를 사용하여 FARGATE IP를 찾을 수 있음(DNS)

4️⃣ Prometheus Metric 데이터 시각화

PROMQL을 활용하여 생성

Title	사용 예시
Total Requests	📄 총 앤드포인트 요청 수
Total Exceptions	*📄 총 에러 수 *
200 Responses	*📄 200 응답수 *
4xx Responses	*📄 4XX 응답수 *
5xx Responses	*📄 5XX 응답수 *
Requests Average Duration	*📄 각 앤드포인트별 응답속도 평균 *
Requests Count	*📄 각 앤드포인트별 요청수 *
*5XX Responses Rate *	*📄 모든 앤드포인트 5xx 에러 발생 시간 *

🔹 결론

⭐ 강력한 시계열 데이터 수집 및 시각화

⭐ 오픈소스 기반의 높은 확장성과 유연성

⭐ PromQL 쿼리 결과를 바로 대시보드로 시각화 가능

이전글에서 Docker Compose를 활용하여 Loki + Grafana 구축하는 글을 보고 오는걸 참고하길 바란다.

https://velog.io/@dev-hsl-960221/Docker-Compose%EB%A5%BC-%ED%99%9C%EC%9A%A9%ED%95%9C-PrometheusLokiGrafana-%EA%B5%AC%EC%B6%95-%EB%B0%8F-%EC%84%9C%EB%B9%84%EC%8A%A4-%EC%9A%B4%EC%98%81

1️⃣ Grafana + Loki 연동

호스트주소가 아닌 loki 키워드로 사용❓

※ Docker Compose에서 여러 서비스를 정의할 때, 같은 네트워크에 속한 컨테이너끼리는 서비스 이름으로 서로를 호출할 수 있습니다.

2️⃣ 대시보드 생성

3️⃣ Query 및 시각화

✅ 앱 서비스들에 대한 환경변수를 app으로 설정

🏷️ Label Filters (라벨 필터)

* Loki는 로그를 라벨(label)로 구분해서 저장합니다.

* appName="$app"은 특정 애플리케이션(app)에 해당하는 로그만 필터링해서 조회하겠다는 의미입니다.

* 여기서 $app은 Grafana에서 정의한 변수(variable)이며, 대시보드 상단에서 선택할 수 있습니다.

🔍 Logfmt 파서 설정

* logfmt는 key=value 형식의 로그를 구조화된 형태로 파싱합니다.

* 파싱된 키는 Grafana에서 필터링, 테이블 출력, 시각화 등에 활용할 수 있어요.

⚙️ 추가 옵션 설명

Strict

체크 시 logfmt 파싱 오류가 있는 로그는 무시합니다.

Keep empty

값이 비어 있는 키도 유지해서 파싱합니다. (예: traceId=)

+ Expression

파싱된 필드를 조건으로 추가 필터링이 가능합니다.

4️⃣ Grafana 시각화 결과

🔹 결론

⭐ 로그 시각화 통합

⭐ 인덱싱이 거의 없기 때문에 리소스 사용량이 적고, 저장 비용도 낮음.

⭐ 운영 중인 시스템에서 로그 기반 이벤트를 빠르게 감지하고 대응할 수 있음.

🔹ECR (Elastic Container Registry)

ECR은 AWS의 Docker 이미지 저장소이다. AWS에 최적화되어 있는 Docker Hub이다.

• Docker 이미지 저장 및 관리
• ECS, EKS, CodePipeline 등과 통합
• 프라이빗/퍼블릭 이미지 레지스트리 지원
• 고속 이미지 다운로드 (S3 기반 저장)

🔹ECS (Elastic Container Service)

ECS는 AWS의 리소스를 활용하는 컨테이너 오케스트레이션 서비스입니다. Kubernetes와 비슷한 역할을 하며, Docker 컨테이너를 실행, 관리, 확장하는 일을 자동으로 처리해줍니다.

• 클러스터 (Cluster) : 컨테이너를 배포할 서버 그룹 (Fargate 또는 EC2 인스턴스 기반)
• 태스크 (Task) : 컨테이너 정의 (도커 이미지, 환경변수, 포트 등 포함)
• 서비스 (Service) : 태스크를 실행시키고 상태를 유지시켜주는 역할 (Auto-scaling, Load balancing 가능)
• 런타임 방식 : - EC2: EC2 인스턴스 위에서 컨테이너 실행 - Fargate: 서버를 신경쓰지 않고 컨테이너만 실행 (서버리스 방식)

1️⃣ ECR 생성

✅ Mutable (기본값)

이미지 태그를 덮어쓸 수 있음 👉 latest 태그에 새로운 이미지를 계속 덮어쓰기 가능

🔒 Immutable

이미지 태그를 한 번 등록하면 덮어쓸 수 없음 👉 태그가 고정되어 배포 안정성 확보에 유리

2️⃣ ECS Cluster 생성

☁️ AWS ECS - Fargate vs EC2

📊 ECS Container Insights 옵션 비교

✅ 추천

• 운영 중인 ECS 서비스를 잘 모니터링하고 디버깅하려면
  ➤ Enhanced Observability 사용하세요.

• 비용이나 성능 고려로 기본 수준만 필요하다면
  ➤ Container Insights 또는 Off 선택도 가능

3️⃣ ECS Task definitions 생성

⚙️ ECS Task Definition - Infrastructure requirements 주요 항목 설명

✅ Tips

• Launch type은 클러스터에서 어떤 환경에서 실행할지 결정하는 핵심 옵션입니다.
• OS/Arch는 사용하는 컨테이너 이미지에 맞춰 정확히 선택해야 실행 오류가 없습니다.
• Fargate 사용 시에는 반드시 Task size 설정이 필요합니다.
  ➤ vCPU와 Memory를 적절히 조합하여 비용 최적화하세요.

⚙️ ECS Task Definition - Container Details 주요 항목 설명

✅ Tips

• Essential 컨테이너가 종료되면 전체 Task도 중지됨 → 중요 서비스는 반드시 Essential로!
• CPU/Memory 제한은 컨테이너가 개별적으로 사용하는 최대치 → Task 전체 리소스와 합쳐서 고려해야 함
• Read-only Root FS 옵션은 보안 강화를 위해 사용되며, 대부분의 앱에서는 켜도 문제 없음

🛠️ ECS Task Definition - 선택 설정 (Optional Settings)

대부분의 경우 생략해도 무방하지만, 특정 상황에서 유용하게 사용됩니다.

✅ 요약

• 일반적인 웹/백엔드 앱: 기본 설정만으로 충분
• 로깅, 재시작 정책, 헬스체크 등은 운영환경에서 점진적으로 적용하면 좋습니다.

4️⃣ ECS Service 생성

👉 클러스터 상세 페이지 상단 메뉴에서 Services 탭을 선택합니다.

👉 Create 또는 서비스 생성하기 버튼을 클릭합니다.

🛠️ ECS Service Environment & Deployment configuration 주요 항목 설명

✅ Tips

Deployment circuit breaker는 꼭 켜두는 것을 추천합니다. → 신규 배포 실패 시 자동으로 이전 상태로 복구되어 장애 방지에 유리합니다.

🛠️ ECS Service Networking 주요 항목 설명

✅ Tips

VPC/Subnet → 퍼블릭 서브넷을 사용하는 경우 퍼블릭 IP 할당을 켜야 외부 통신 가능 → 프라이빗 서브넷에서는 NAT Gateway 등을 통해 외부 통신 필요

Security group → 최소 포트만 열고, 특정 IP만 허용하는 식으로 보안 원칙 준수

Public IP → 외부 API 호출, S3 접근 등 인터넷 접속이 필요한 경우 반드시 켜야 함

🛠️ ECS Service Load balancing 주요 항목 설명

✅ Tips

• ALB vs NLB

  • 웹 서비스나 API 서버 → ALB 추천
  • 고성능 TCP 서비스 → NLB 고려

• Health check 경로는 200 OK 응답을 반환해야 정상으로 간주되므로 /health, /actuator/health 등의 경로로 설정 필요

• Deregistration delay는 무중단 배포를 위해 Task가 종료되기 전 클라이언트 요청을 모두 처리할 수 있도록 일정 시간 대기하는 설정입니다.

• Listener 설정이 잘못되면 ALB가 요청을 수신하지 못하므로 주의하세요.

🛠️ ECS Service Service Discovery 주요 항목 설명

** 👉 ECS 내에서 서비스 간 통신을 DNS 기반으로 자동화하는 기능입니다. 특히 서비스 이름 기반으로 다른 서비스의 IP 주소를 찾을 수 있게 해주는 기능 **

🔹 결론

⭐ 서버 관리가 필요 없는 완전한 서버리스 아키텍처

• EC2 관리 불필요 → 오토스케일, 패치, 유지보수 부담 ↓, 인프라 비용은 실제 사용한 리소스만큼만 지불

⭐ 서비스 간 통신 구조가 간단

• Service Discovery를 활용하면 DNS 기반으로 다른 ECS 서비스에 바로 접근 가능
• 로드밸런서 없이도 마이크로서비스 연결 가능 ( ※ EC2 프로메테우스 환경에서 dns_sd_configs 활용 가능 )

⭐ 높은 확장성과 가용성

1) docker-compse 설정

services:

  prometheus:
    image: prom/prometheus:latest                                                  # Prometheus 최신 이미지 사용
    container_name: prometheus                                                     # 컨테이너 이름 지정
    ports:
      - "9090:9090"                                                                # 호스트 포트 9090 → 컨테이너 포트 9090
    volumes:
      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml               # 호스트의 설정 파일을 컨테이너로 마운트   
    command:
      - --config.file=/etc/prometheus/prometheus.yml                             # 설정 파일 경로 지정 (옵션)                   
    networks:
      - prometheus                                                               # prometheus 네트워크에 연결

  loki:
    image: loki:latest                                                            # Loki 최신 이미지 사용 (공식 이미지는 grafana/loki 사용 권장)
    container_name: loki                                                          # 컨테이너 이름 지정
    user: "$UID:$GID"                                                             # 현재 사용자 권한으로 실행 (권한 문제 방지)
    ports:
      - "3100:3100"                                                               # Loki 포트 매핑 (기본 포트 3100)
    volumes:
      - ./loki/loki.yml:/etc/loki/local-config.yaml                               # Loki 설정 파일 마운트       
      - ./loki:/var/loki                                                        # 로그 데이터 저장 디렉토리 마운트
    command: -config.file=/etc/loki/local-config.yaml                             # 설정 파일 지정                     
    networks:
      - loki                                                                      # loki 네트워크에 연결

  grafana:
    image: grafana:latest                                                         # Grafana 최신 이미지
    container_name: grafana                                                      # 컨테이너 이름 지정
    user: "$UID:$GID"                                                             # 현재 사용자 권한으로 실행
    ports:
      - "3000:3000"                                                               # Grafana 웹 포트 (기본 3000)
    volumes:
      - ./grafana:/var/lib/grafana                                                # Grafana 데이터 디렉토리 마운트 (대시보드, 설정 등 저장)                             
    depends_on:
      - prometheus                                                                # Prometheus 서비스가 먼저 시작되도록 설정
      - loki                                                                      # Loki 서비스가 먼저 시작되도록 설정
    networks:
      - prometheus                                                                # Prometheus 네트워크에 연결 (메트릭 수집용)
      - loki                                                                      # Loki 네트워크에 연결 (로그 수집용)

networks:                                                                        # 사용자 정의 네트워크 설정
  prometheus:
    driver: bridge                                                                # 기본 브리지 네트워크 사용
  loki:
    driver: bridge                                                               # 로그 관련 컨테이너용 네트워크

✅ docker-compose down

• 현재 실행 중인 모든 컨테이너, 네트워크, 볼륨 등을 종료 및 삭제합니다.
• 기본적으로 네트워크와 컨테이너를 삭제하고, 볼륨은 유지됩니다. (--volumes 옵션을 주면 볼륨도 삭제됨)

  ✅ docker-compose up -d

• docker-compose.yml에 정의된 서비스를 백그라운드(-d)로 실행합니다.
• 변경된 부분만 다시 빌드하고 실행합니다.

2) Spring Application 에서 프로메테우스 서버로 메트릭 데이터를 Export

1. build.gradle 의존성 추가

implementation 'io.micrometer:micrometer-registry-prometheus'

2. yml 파일 설정

management:
  endpoints:
    web:
      exposure:
        include: prometheus
  endpoint:
    prometheus:
      enabled: true

3) Spring Application 에서 Loki 서버로 로그를 전달하는 Appender 설정

1. build.gradle 의존성 추가

implementation 'com.github.loki4j:loki-logback-appender:1.5.1'

2. logback 설정

<!-- Loki로 WARN과 ERROR 레벨의 로그만 전송하는 appender 설정 -->
<appender name="LOKI" class="com.github.loki4j.logback.Loki4jAppender">

    <!-- 로그 레벨 필터 설정: WARN 이상만 전송됨 (WARN, ERROR) -->
    <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
        <level>WARN</level> <!-- WARN과 ERROR 레벨만 전송 -->
    </filter>

    <!-- Loki HTTP Push 설정 -->
    <http>
        <!-- Loki 수신 URL (IP 또는 도메인) -->
        <url>http://{Loki 서버 URL}:3100/loki/api/v1/push</url>
    </http>

    <!-- 로그 포맷 설정 -->
    <format>
        <!-- 라벨(label): Loki의 로그 분류 기준으로 사용됨 -->
        <label>
            <!-- 예: appName, host, 로그레벨 등을 라벨로 전송 -->
            <pattern>appName=weather-v2-dev,host=${HOSTNAME},level=%level</pattern>
        </label>

        <!-- 메시지 포맷: 실제 로그 내용 -->
        <message>
            <!-- 로그 출력 형식 설정 (스레드명, 로그레벨, 로거, 메시지) -->
            <pattern> [%thread] %-5level %logger{36} - %msg%n</pattern>
        </message>
    </format>

</appender>

4) preometheus.yml 설정

🚨ECS + FARGATE 서비스 디스커버리 연동 시 : dns_sd_config + Cloud Map 사용

global:
  scrape_interval: 1s                             # 메트릭 수집 주기 (기본: 1초)
  evaluation_interval: 1s                         # 알림 룰 평가 주기 (기본: 1초)



  - job_name: "test-one"              
    metrics_path: "/actuator/prometheus"
    static_configs:
      - targets: ["test.application.com"]
    relabel_configs:
      - source_labels: ['__address__']
        target_label: 'instance'
        replacement: '샘플테스트(첫번째)'
    scheme: https

  - job_name: "test-two"                      
    metrics_path: "/actuator/prometheus"
    dns_sd_configs:                              # DNS 기반 서비스 디스커버리 사용
      - names:
          - 'test-two-api.test-two.dev'           # 서비스 도메인 {
        type: 'A'                                # A 레코드 조회
        port: 80                                 # HTTP 포트
    relabel_configs:
      - source_labels: ['__address__']
        target_label: 'instance'
    scheme: https       

✅ static_configs

정적인 타겟 설정 – IP나 도메인 주소를 직접 명시

• 타겟을 수동으로 입력
• IP 또는 도메인 주소가 고정되어 있을 때 사용
• 간단한 구조, 테스트/개발 환경에서 많이 사용

  사용 예

• EC2, ECS, 로드밸런서 등에 도메인이나 IP로 접근 가능할 때
• 수가 많지 않고 변경되지 않는 서비스들

✅ dns_sd_configs

DNS 기반의 서비스 디스커버리 – DNS 쿼리를 통해 동적으로 타겟을 찾음

• 서비스가 등록된 도메인을 기준으로 DNS A/AAAA 레코드를 조회
• 클러스터 내부 서비스(DNS가 자동 관리되는 환경, 예: Kubernetes, ECS 서비스 디스커버리 등)에 적합
• 대상이 늘어나거나 줄어드는 경우 자동 반영 가능 ( ※핵심 )

  사용 예

• AWS ECS, Kubernetes 등 동적으로 생성되는 서비스
• DNS를 통해 클러스터 서비스 엔드포인트를 노출할 때

5) Loki 설정

auth_enabled: false                                                  # 인증 기능 비활성화 (기본적으로 내부 네트워크에서 사용 시 인증 생략 가능)

server:
  http_listen_port: 3100                                              # Loki 서버가 HTTP 요청을 수신할 포트 설정

common:
  instance_addr: 127.0.0.1                                          # Loki 인스턴스의 주소 (gossip ring에 사용)
  path_prefix: /var/loki                                              # Loki가 내부적으로 파일을 저장할 기본 경로
  storage:
    filesystem:                                                      # 로컬 파일 시스템 기반 저장소 사용
      chunks_directory: /var/loki/chunks                              # 로그 청크 데이터를 저장할 디렉토리
      rules_directory: /var/loki/rules                                 # 룰 파일 저장 경로 (알림 룰 등)
  replication_factor: 1                                              # 복제 개수 설정, 1은 단일 노드에서 사용
  ring:
    kvstore:
      store: inmemory                                                  # 키-값 저장소로 인메모리 방식 사용 (단일 노드에 적합)

query_range:
  results_cache:
    cache:
      embedded_cache:
        enabled: true                                                  # 쿼리 결과에 대한 캐시 기능 활성화
        max_size_mb: 100                                             # 캐시 최대 크기 (MB 단위)

schema_config:
  configs:
    - from: 2020-10-24                                              # 이 날짜부터 적용할 스키마 설정
      store: tsdb                                                      # 저장 방식으로 TSDB(Time Series Database) 사용
      object_store: s3                                              # 청크 데이터를 저장할 오브젝트 스토어 타입
      schema: v12                                                      # Loki 스키마 버전 (최신 버전 중 하나)
      index:
        prefix: index_                                              # 인덱스 프리픽스 (S3에 저장될 키 이름의 접두어)
        period: 24h                                                  # 인덱스를 하루 단위로 생성

storage_config:
  aws:
    s3: tnear-loki-log                                              # 사용할 S3 버킷 이름
    region: ap-northeast-2                                          # S3 리전 (서울)
    access_key_id: {AWS_ACCESS_KEY}                                  # AWS 접근 키 (보안상 주의 필요)
    secret_access_key: {AWS_SECRET_ACCESS_KEY}                      # AWS 비밀 접근 키 (보안상 주의 필요)

6) Grafana 접속

🔹 결론

⭐ Prometheus 메트릭 데이터 + Loki 로그를 연동하여 시각화

⭐ Loki는 레이블 기반의 최소 인덱싱 구조 사용,

⭐ Prometheus는 자체 DB와 압축 구조로 고성능 고효율적임

⭐ Loki와 Prometheus 설정 파일 기반 운영이 쉬움

⭐ 오픈소스 기반으로 별도 라이선스 비용이 없다.

시각화 대시보드 구성에 관해서는 다음 글에서 진행하도록 하겠다. 😊😊😊😊😊😊😊😊

*1. 특정 EC2 인스턴스 내 Docker로 Jenkins 컨테이너 운영 2. Jenkins Pipeline 내에서 Git Branch Checkout 정의 3. Jenkins Pipeline 내에서 AWS CLI 사용자 정의 4. Jenkins Pipeline 내에서 Dockerfile 정의 5. Jenkins Pipeline 내에서 Slack Notification 정의 6. Jenkins Pipeline 내에서 Build Gradle 정의 7. Jenkins Pipeline 내에서 ECR Registry & ECS Deploy 정의 8. Jenkins Pipeline 내에서 커밋 로그 추출 Slack WebWook 정의 *

🔹 파이프라인을 사용하기 앞서 필요한 Plugin

1️⃣ AWS Credentials Plugin

2️⃣ Pipeline: AWS Steps Plugin

3️⃣ Slack Notification Plugin

4️⃣ Git plugin

🔧 파이프라인 구성 요소 설명

• agent 👉 어디서 실행할지를 정의 (any, label, docker, 등)
• environment 👉 공통 환경변수 설정
• stages 👉 단계들을 그룹핑
• stage 👉 개별 작업 단계 (예: 빌드, 테스트, 배포 등)
• steps 👉 해당 단계에서 수행할 작업들
• post 👉 성공/실패 후의 후처리 작업 정의

🚨 AWS Credentials 정의

1) Jenkins 관리 -> Credentials

2) AWS Credentials 생성

• AWS Access Key Id : 공개적으로 식별 가능한 키

• AWS Secret Access Key : 해당 Access Key ID에 대응하는 비밀번호 같은 비밀 키

※ 젠킨스 파이프라인 ECR Registry & ECS Deploy 해당 Stage 에서 사용 예정

ex) withAWS(credentials: '{AWS Credentials ID}', region: {AWS REGION}

※ 설명하기 앞서서 해당 글에 Stage View는 그림과 같다.

pipeline {
  agent any

  environment {
    BITBUCKET_CREDENTIALS  = 'bc2fa053-e540-48bc-b7f7-b504430a63c9'                   // Bitbucket 자격 증명 ID
    AWS_REGION             = 'ap-northeast-2'                                        // AWS 리전
    ECR_URI                = '998251115309.dkr.ecr.ap-northeast-2.amazonaws.com'   // ECR URI
    ECR_REPOSITORY_NAME    = 'test'                                                 // ECR 리포지토리 이름
    ECS_CLUSTER_NAME       = 'test-cluster'                                      // ECS 클러스터 이름
    ECS_SERVICE_NAME       = 'test-service'                                      // ECS 서비스 이름
    ECR_IMAGE_TAG          = 'latest'                                          // 이미지 태그
    SLACK_CREDENTIALS      = 'slack'                                          // Slack 자격 증명 ID
    SLACK_CHANNEL          = '#test-notification'                             // Slack 채널
    COMMIT_FILE            = "previous_commit_hash.txt"                        // 커밋 해시 저장 파일
    PREVIOUS_COMMIT        = ''                                               // 이전 커밋 해시 (동적 할당용)
    CURRENT_COMMIT         = ''                                           // 현재 커밋 해시 (동적 할당용)
  }

  stages {

    stage('Checkout Bitbucket') {
      steps {
        git branch: 'test',
            credentialsId: BITBUCKET_CREDENTIALS,
            url: '{브랜치 주소}'
      }
    }

    stage('Write Dockerfile') {
      steps {
        script {
          // 동적으로 Dockerfile 작성
          writeFile file: 'Dockerfile', text: '''
            FROM amazoncorretto:21
            ARG JAR_FILE=./build/libs/test-0.0.1-SNAPSHOT.jar
            COPY ${JAR_FILE} app.jar
            ENV SPRING_PROFILES_ACTIVE=dev
            ENTRYPOINT ["java", "-Xms3g", "-Xmx3g", "-XX:ActiveProcessorCount=2", "-XX:MaxRAMPercentage=75.0", "-XX:InitialRAMPercentage=75.0", "-jar", "app.jar"]
          '''
        }
      }
    }

    stage('Prepare Slack Notification') {
      steps {
        script {
          // 이전 커밋 해시 확인 (파일에서 읽거나 git에서 가져옴)
          if (fileExists(COMMIT_FILE)) {
            PREVIOUS_COMMIT = readFile(COMMIT_FILE).trim()
          } else {
            PREVIOUS_COMMIT = sh(
              script: "git rev-parse HEAD~1",
              returnStdout: true
            ).trim()
          }

          // 현재 커밋 해시 가져오기
          CURRENT_COMMIT = sh(
            script: "git rev-parse HEAD",
            returnStdout: true
          ).trim()
        }
      }
    }

    stage('Slack Build Notification') {
      steps {
        script {
          // 빌드 시작 알림
          slackSend(
            color: "#439FE0",
            channel: SLACK_CHANNEL,
            message: "*프로젝트 이름 : ${env.JOB_NAME}*\n*빌드번호 : ${env.BUILD_NUMBER}*\n*빌드실행 :jenkins_pepe_1:*",
            tokenCredentialId: SLACK_CREDENTIALS
          )
        }
      }
    }

    stage('Build Gradle') {
      steps {
        // Gradle 빌드 실행
        sh 'chmod +x ./gradlew'
        sh './gradlew clean build -Dorg.gradle.java.home=/usr/lib/jvm/jdk-21'
      }
    }

    stage('ECR Registry & ECS Deploy') {
      steps {
        // AWS 인증 및 배포 작업
        withAWS(credentials: 'aws-credentials-id', region: AWS_REGION) {
          sh '''
            aws ecr get-login-password --region ${AWS_REGION} | docker login --username AWS --password-stdin ${ECR_URI}

            docker build -t ${ECR_REPOSITORY_NAME} .
            docker tag ${ECR_REPOSITORY_NAME}:${ECR_IMAGE_TAG} ${ECR_URI}/${ECR_REPOSITORY_NAME}:${ECR_IMAGE_TAG}
            docker push ${ECR_URI}/${ECR_REPOSITORY_NAME}:${ECR_IMAGE_TAG}

            docker rmi ${ECR_URI}/${ECR_REPOSITORY_NAME}:${ECR_IMAGE_TAG}
            docker rmi ${ECR_REPOSITORY_NAME}:${ECR_IMAGE_TAG}

            aws ecs update-service --cluster ${ECS_CLUSTER_NAME} --service ${ECS_SERVICE_NAME} --force-new-deployment
          '''
        }
      }
    }
  }

  post {
    success {
      script {
        // 변경된 커밋 로그 추출
        def newCommits = sh(
          script: "git log ${PREVIOUS_COMMIT}..${CURRENT_COMMIT} --pretty=format:'%s [%an]'",
          returnStdout: true
        ).trim()

        // 최신 커밋 해시 저장
        writeFile file: COMMIT_FILE, text: CURRENT_COMMIT

        // Slack 알림 - 빌드 성공
        def message = newCommits ?
          newCommits.split('\n').collect { it + "  :jenkins_pepe_2:" }.join('\n') :
          "*반영된 커밋 없음*"

        slackSend(
          color: "#36a64f",
          channel: SLACK_CHANNEL,
          message: "*빌드성공 : ${env.JOB_NAME}*\n*빌드번호 : ${env.BUILD_NUMBER}*\n*반영된 커밋 목록*\n${message}",
          tokenCredentialId: SLACK_CREDENTIALS
        )
      }
    }

    aborted {
      slackSend(
        color: "#ffcc00",
        channel: SLACK_CHANNEL,
        message: "*Build Aborted: ${env.JOB_NAME} - ${env.BUILD_NUMBER}*",
        tokenCredentialId: SLACK_CREDENTIALS
      )
    }

    unstable {
      slackSend(
        color: "#ffcc00",
        channel: SLACK_CHANNEL,
        message: "*Build Unstable: ${env.JOB_NAME} - ${env.BUILD_NUMBER}*",
        tokenCredentialId: SLACK_CREDENTIALS
      )
    }

    failure {
      script {
        // 실패한 빌드의 커밋 로그 추출
        def newCommits = sh(
          script: "git log ${PREVIOUS_COMMIT}..${CURRENT_COMMIT} --pretty=format:'%s [%an]'",
          returnStdout: true
        ).trim()

        // 커밋 해시 저장
        writeFile file: COMMIT_FILE, text: CURRENT_COMMIT

        // Slack 알림 - 빌드 실패
        def message = newCommits ?
          newCommits.split('\n').collect { it + "  :pepe2:" }.join('\n') :
          "*반영된 커밋 없음*"

        slackSend(
          color: "#ff0000",
          channel: SLACK_CHANNEL,
          message: "*빌드실패 : ${env.JOB_NAME}*\n*빌드번호 : ${env.BUILD_NUMBER}*\n*반영된 커밋 목록*\n${message}",
          tokenCredentialId: SLACK_CREDENTIALS
        )
      }
    }
  }
}

1. 특정 EC2 인스턴스 내 Docker로 Jenkins 컨테이너 운영 2. Jenkins에서 특정 Bitbucket Repository branch 를 Pull 받은 이후 Execute Shell을 활용하여 gradle clean build 3. 아티팩트(Jar)를 SSH를 통해 특정 호스트 내 특정 디렉토리로 전송 4. 쉘 스크립트와 DockerFile을 통해 ECR 이미지를 만들어주고 ECS 클러스터에 배포 5. 해당 브랜치에 반영된 Git Commit Log를 Slack Webhook으로 전송

해당 글에서는 Jenkins Images를 Pull 받고 Docker Container로 동작하는 부분은 제외 하도록 하겠다. Jenkins Home 까지 진입이 된 상태에서 설명된 글이기 때문에 Jenkins를 컨테이너로 동작하는 과정을 알고 싶다면 잘 정리 되어있고 보기 좋은 참조 문서들이 많기 때문에 다른 글을 참고하기 바란다.

1️⃣ Bitbucket App Passwrod 발급

1) Create App Password

2) Permissions 지정

최소한의 권한은 소스코드 관리와 Webhook을 받기 위해 Repository, Webhook 접근권한이 필요하다. ※ 추가로 필요한 부분들은 체크 이후 사용하면 될 것 같다

3) App Password 발급

*🚨 고려 사항 : 발급 이후 딱 한 번만 확인이 가능하므로 별도의 저장소나 개인이 관리가 필요함 *

2️⃣ Jenkins Bitbucket Credentials 생성

1) Jenkins 관리 -> Crdentials

2) Add Credentials

3) Create Credentials

• Username : 형상관리 계정 이름을 나타내는게 대부분이다.

• Password : Bitbucket에서 생성된 App Password
• ID : Jekins 내에서 Credentials를 식별하는 식별자
• Description : 해당 Credentials를 대한 간단한 설명

3️⃣ Publish over SSH Server 설정

1) Publish Over SSH 설치

설치가 안 된 경우 Available pligins 에 들어가서 플러그인을 설치하면 된다.

2) Jenkins 관리 -> System -> SSH 설정

• Name : SSH 서버 별칭

• Hostname : SSH 서버 호스트 주소
• Username : SSH 서버 아이디
• Remote Directory : SSH 서버 Remote 경로 위치
• *Passphrase / Password * : SSH 서버 비밀번호 🚨 ※ SSH Password 설정은 sshd_config 파일안에 PasswordAuthenticateion 상태 값을 yes 로 변경

4️⃣ Slack Notification 설정

1) Slack Jenkins CI 플러그인 추가 및 토큰 생성

**🚨 토큰값은 Jekins Slack Credential 설정시 사용하기 때문에 기억해두기!!

2) Slack Notification Plugin 설치

설치가 안 된 경우 Available pligins 에 들어가서 플러그인을 설치하면 된다.

3) Slack Credential 설정

• Secret : 1번에서 만든 Slack Jenkins CI 토큰

• ID : 채널 ID 또는 고유 ID 를 지정
• Description : 해당 Credential 설명

4) Jenkins 관리 -> System -> Slack 설정

• Workspace : Slack 워크스페이스 이름

• Credential : Jenkins가 Slack API를 사용하기 위한 인증 정보 (토큰) / 3번에서 만든 Credential 적용
• *Default channel / member id * : 기본적으로 메시지가 전송될 Slack 채널 (#채널명) 또는 사용자 (@사용자명)

5️⃣ 쉘 스크립트 및 DockerFile 작성

1) SSH Remote Directory 경로 안에 DockerFile 생성

# Amazon에서 제공하는 Corretto OpenJDK 11 이미지를 기본 이미지로 사용합니다.
FROM amazoncorretto:11

# 빌드시 전달받을 jar 파일의 경로를 정의합니다. 기본값은 현재 디렉토리의 weather-1.0.0-BUILD-SNAPSHOT.jar 파일입니다.
ARG JAR_FILE=./weather-1.0.0-BUILD-SNAPSHOT.jar

# 전달받은 jar 파일을 컨테이너 내부에 app.jar라는 이름으로 복사합니다.
COPY ${JAR_FILE} app.jar

# Spring 프로필을 'dev' 환경으로 활성화합니다.
ENV SPRING_PROFILES_ACTIVE=dev

# 컨테이너 내부의 시간대를 한국 시간으로 설정합니다.
ENV TZ=Asia/Seoul

# 컨테이너가 시작될 때 실행될 명령어입니다.
# 최소 힙 메모리 512MB, 최대 힙 메모리 2048MB로 JVM을 실행하며, app.jar를 실행합니다.
ENTRYPOINT ["java", "-Xms512m", "-Xmx2048m", "-jar", "app.jar"]

• FROM : Docker 이미지를 만들 때 기반 이미지(Base image) 를 지정할 때 사용

• ARG : Docker 이미지 빌드 과정 중에 사용할 수 있는 인자(argument)를 설정
• COPY : 로컬에 있는 파일 또는 디렉터리를 이미지 내부로 복사
• ENV : 컨테이너 내부에서 사용할 환경 변수를 설정
• ENTRYPOINT : Docker 컨테이너가 실행될 때 기본적으로 실행되는 명령어를 지정

2) SSH Remote Directory 경로 안에 쉘 스크립트 생성 ( ※ VI 편집기 )

🚩 1단계: AWS ECR 로그인 (인증)

🚩 2단계: Docker 이미지 빌드하기

🚩 3단계: Docker 이미지에 ECR 레지스트리 태그 붙이기

🚩 4단계: ECR로 Docker 이미지 푸시하기 (업로드)

🚩 5단계: 로컬 이미지 삭제하기 (정리)

🚩 6단계: AWS ECS 서비스 재배포 (이미지 업데이트 적용)

#!/bin/bash

# AWS ECR 로그인 (도커 클라이언트 인증)
aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin 998251115309.dkr.ecr.ap-northeast-2.amazonaws.com

# Docker 이미지 빌드 (로컬 Dockerfile 사용)
docker build -t dev-weather /home/admin/weather-dev

# Docker 이미지 태그 지정 (ECR 레포지토리에 맞게 변경)
docker tag dev-weather:latest 998251115309.dkr.ecr.ap-northeast-2.amazonaws.com/dev-weather:latest

# AWS ECR로 Docker 이미지 업로드
docker push 998251115309.dkr.ecr.ap-northeast-2.amazonaws.com/dev-weather:latest

# 로컬 Docker 이미지 삭제 (디스크 공간 확보)
docker rmi 998251115309.dkr.ecr.ap-northeast-2.amazonaws.com/dev-weather:latest
docker rmi dev-weather:latest

# AWS ECS 서비스 강제 재배포 (새로운 이미지 적용)
aws ecs update-service --cluster dev-weather-cluster --service dev-weather-service --force-new-deployment

6️⃣ Jenkins FreeStyle Project 구성

1) FreeStyle Project 생성

2) FreeStyle Project 구성

1. Git 소스코드 관리

• Repository URL : Git Repository URL

• Credentials : Jenkins에서 등록한 Bitbucket Credentials 설정

• Branch Specifier : 브랜치명

  Git Trigger를 제외한 이유 ❓

  • 불필요한 빌드 방지

  • 의도적인 수동 제어

🚨 꺼진불도 다시보자!!!!!

2. Build Steps

1. chmod +x ./gradlew

1) 이 명령어는 현재 디렉토리에 있는 gradlew 파일을 실행 가능(executable)하게 만드는 명령입니다.
2) chmod 명령어는 파일의 접근 권한(permission)을 변경하는 명령어입니다.
3) +x 옵션은 파일을 실행할 수 있는 권한을 부여하는 의미이며, 주로 스크립트나 실행파일을 실행하기 위해 설정합니다.
4) ./gradlew는 Gradle Wrapper로, 프로젝트에서 정의한 Gradle 버전을 자동으로 다운로드하고 빌드합니다.

🚨 즉, 이 명령어가 없으면 ./gradlew 실행 시 Permission denied 에러가 발생할 수 있습니다.

2. ./gradlew clean build

1) 이 명령어는 Gradle 프로젝트를 빌드하는 과정입니다.
2) clean은 이전 빌드에서 생성된 모든 빌드 결과물을 삭제하는 작업입니다.
3) 주로 이전 빌드로 인해 발생할 수 있는 충돌이나 문제를 방지하기 위해 사용합니다.
4) build는 프로젝트의 소스를 컴파일하고, 테스트를 수행한 후 빌드 결과물(JAR/WAR 등)을 생성합니다.

3. 빌드 후 조치

• Name : Jenkins System에서 설정한 SSH

• Source files : 빌드된 결과물(artifact)에 대한 경로 위치

• Remove prefix : 접두사로 지정된 경로를 제거한 후 나머지 경로만 사용

• Remote directory : 전송된 아티팩트를 대상 서버 원하는 경로

• Exec command : 아티팩트를 원격 서버에 전송한 후 실행할 명령어

• ** 쉘 스크립트에 배포에 대한 명령어를 정의해놨으니 쉘 스크립트를 실행!!!!! ***

4. Slack Webhook

• Notification message includes : Jenkins가 Slack으로 보낼 알림 메시지에 포함할 항목들을 선택할 수 있도록 해주는 설정입니다.

• Credential : Jenkins System에서 설정한 Slack Credentials

🔹 결론

Jenkins에서 Pipeline(Job as Code) 방식이 더 많이 사용되고 권장되고 있지만 Pipeline 대비 Freestyle 장점을 적어보겠다.

⭐ 별도의 스크립트 작성 없이 플러그인을 쉽고 간편하게 추가 및 사용 가능 ⭐ 코드 없이 직관적인 GUI 기반의 관리 ⭐ 빠르고 쉬운 설정이 가능하다. 즉, 구성 속도가 빠르다. ⭐ 러닝커브가 낮기 때문에 신규 사용자도 진입 장벽이 매우 낮은 장점이 있다.

단어 그대로 통합이다. 서로 다른 서비스나 소프트웨어를 하나의 시스템처럼 동작하게 만드는 것이다. 쉽게 말하자면 서로 다른 독립적인 도구나 서비스가 정보를 주고받으면서 함께 동작하도록 연결하는 것

🔹 Integration 하는 이유

협업(co-work)의 중요성은 항상 소통이 중요하다고 생각한다. 하지만 바쁘거나 다른 업무로 인한 인터럽트가 발생하면 우리는 놓치는 부분들이 많이 발생한다. 그렇기 때문에 Integration을 통한 즉각적인 정보 공유를 할 수 있고 어느 정도 말을 하지 않아도 누가 어떤 업무를 진행 중인지 파악을 할 수가 있다. 수동적인 작업이 줄어듦과 동시에 효율성이 증가한다.

개발팀 중에서 BE 부서는 현재 Bitbucket 형상 관리를 통한 버전관리, 소스코드 관리, 변경 관리를 진행하고 있기 때문에 Integration을 구현하는 방법중 하나인 Webhook을 통해 이벤트를 Slack으로 전달하는 프로세스를 설명하는 글입니다.

1️⃣ Repository -> Settings

※ 만약 사이드바에 "Repository settings" 부분이 보이지가 않는다면 해당 레포지토리의 접근 권한을 부여 받아야함 Admin : 레포지토리 설정 관리 가능

2️⃣ Slack -> Settings

3️⃣ Add New Workspace / Add Subscription

Webhook을 보내기위한 Workspace와 Channel을 지정할수가있다. 본인은 이미 해당 bitbucket-notification이라는 채널에 Webhook을 보내고 있기 때문에 비활성화로 보이고 있다.

4️⃣ Branch 및 Notifications 지정

특정 브랜치마다 Notification 종류를 다르게 가져갈 수 있다. 본인은 main을 제외한 모든 브랜치에 대해서는 Pull Request, Branch, Commits 관련한 모든 노티를 적용 main 브랜치에 대해서는 Deploy 관련한 노티만 적용

5️⃣ Slack Webhook

🔹 결론

⭐ Webhook을 통한 트래킹이 가능해지고 History가 남게 되므로 추적과 관찰이 가능 ⭐ 즉각적인 업무 공유가 가능해지고 어느 정도 누군가의 업무 파악이 가능

간단하게 한 문장으로 정리하자면 여러 개의 프로파일을 그룹으로 묶어서 함께 적용할 수 있도록 하는 기능 이다. 즉, 특정 프로파일을 활성화하면 연관된 프로파일들을 자동으로 포함할 수 있도록 도와줍니다.

🔹 왜 Profile Group을 사용했을까

application.yml 파일 안에 모든 환경별 설정을 계속해서 넣었을 때 유지보수나 가독성이 현저히 떨어지는 부분이 발생함 또 환경 설정 파일이 비대화 및 복잡도가 커지다보니 중복 설정이 발생하기도 했다. 이를 해결하기 위한 고민을 했던 것 같다. 더 유연한 프로파일 구성을 하는 방법이 있는지.... 🤔🤔

✅ 기존 방식 ( AS-IS )

application.yml 파일 안에 모든 설정값을 넣어서 관리하기 시작했다. 이때 내 생각은 설정값이 지나치게 길어지는 것보다 파일이 많아지는 게 오히려 개발 관점에서 불편함이 발생할 거라고 생각했었다.

✅ 개선 이후 방식 ( TO-BE )

1. application.yml을 목적에 맞게 분리

2. Profile Group 적용

3. Run Application Edit Configuration Active Profiles 설정

목적에 맞게 프로파일을 구분지어 관리하기 시작했다. 공통부분들은 묶어서 관리하였고 배포 환경별 설정들을 쉽게 조합하기가 쉬워졌다.

🔹 결론

⭐ Profile Group을 사용하면 중복 설정을 줄이고 가독성과 유지보수가 용이해진다. ⭐ 환경별 설정을 쉽게 관리할 수가 있고 더 유연한 프로파일 구성이 가능해진다.