Ch1. kafka 시작하기

kafka를 시작하기 앞서 kafka는 단순 데이터베이스 이상으로 스트림으로서의 데이터에 초점을 맞추고 있다. 분산 클러스터 형태를 가지고 모든 종류의 데이터 스트림을 가지고 있어서 확장 가능한 플랫폼 역할도 가능하다. 가령 매우 큰 규모의 데이터 스트림을 저장하고 지속적으로 처리하는 것이 가능하다. low latency라는 특성을 갖기 때문에 다른 빅데이터를 다루는 프로그램과 달리 비지니스 애플리케이션의 코어로 사용이 가능하다. 이런 매력적인 특성을 가지고 있기 때문에 이전 프로젝트에서 도입을 하려고 했으나 개인적인 사정으로 빠지게 되어서 매우 아쉬움을 느끼고 있다. 이 kafka를 배우려고 할 때 도움을 주신 분들에게 감사함을 느끼며 첫 글을 개시하고자 한다. kafka 시작하기 조직에서 데이터를 이동시키는 작업에서 더 적은 노력이 들수록 핵심 비지니스에 집중이 가능하다. 그래서 data-driven enterprise에서 파이프라인이 중요한 이유이다. 발행/구독 메시지 전달 패턴 전송자가 데이터를 보낼 때 직접 수신자로 보내지 않는 구조이다. 발행자 Producer는 메시지를 Broker에 발행한다. 구독자 Consumer는 필요한 메시지만 구독하여 가져간다. 발행/구독 시스템에는 대개 발행된 메시지를 중계하는 Broker가 있다. 이전의 발행자와 구독자가 직접 연결된 형태에는 애플리케이션의 종류와 개수가 많아질 수록 추적이 힘들다는 단점이 존재한다. 이를 개선한 형태로 지표를 받는 하나의 애플리케이션을 만들고 이에 관해 질의를 제공가능한 서버를 둔다. 이처럼 지표를 다루는 것 이외에 로그 메시지에 대해서도 비슷한 작업을 해주면된다. 그리고 프론트엔드 사이트에서 사용자 활동을 추적해서 정보를 개발자에게 제공하거나 보고서를 사용할 때도 쓸 수가 있다. 목적이 많아질수록 아래와 같이 중복이 많아지고 버그와 한계도 제각각인 다수의 데이터 큐 시스템을 유지 관리해야 한다. 비지니스가 확장됨에 따라 함께 확장되는, 일반화된 유형의 데이터를 발행하고 구독가능한 중앙 집중화된 시스템이 필요해졌다. 메시지와 배치 메시지 데이터의 기본단위 배치 단위로 저장된다. 오버 헤드를 줄이고 latency와 thoughtput 사이에 trade-off를 발생시킨다. 즉, 배치 크기가 커질수록 시간당 처리하는 메시지수가 늘어나고, 전달되는데 걸리는 시간이 늘어난다. 키라 불리는 메타데이터를 포함한다. 스키마 메시지는 내용을 이해하기 쉽도록 JSON, XML 양식으로 보내는 것이 권장된다. 실무에서는 대부분의 서비스는 메시지 형식으로 JSON을 사용하지만, 대규모 시스템에서는 Schema Registry와 함께 Avro 또는 Protobuf를 사용하는 경우가 많다. 토픽 데이터베이스의 테이블이나 파일 시스템의 폴더와 유사 토픽은 메시지를 저장하는 논리적인 단위이다. 실제 데이터는 토픽 내부의 여러 파티션에 분산 저장된다. 여러 개의 파티션으로 나뉘어진다. 토픽 안의 메세지 전체에 관해 순서는 보장되지 않는다. 다만 단일 파티션 내에서 순서가 보장된다. 스트림: 파티션의 개수와 상관없이 하나의 토픽에 저장된 데이터로 간주, 프로듀서로부터 컨슈머로의 데이터 흐름을 나타낸다. 프로듀서와 컨슈머 카프카 클라이언트는 시스템의 사용자이고 기본적으로 프로듀서, 컨슈머 두가지로 나뉜다. 여기서 고급 클라이언트로 데이터 통합에 사용되는 카프카 커넥트 api, 스트림 처리에 사용되는 카프카 스트림즈이다. 프로듀서 새로운 메시지를 생성한다. 다른 발행/구독 시스템에서 발행자, 작성자라고 불린다. 기본적으로 프로듀서는 메시지를 쓸 때 토픽에 속한 파티션들 사이에 고르게 나눠서 설치된다. 메시지 키와 키 값의 해시를 특정 파티션으로 대응시켜 주는 파티셔너를 사용해서 구현된다. 컨슈머 메시지를 읽는다. 다른 발행/구독 시스템에서는 구독자, 독자라고 한다. 1개 이상의 토픽을 구독해서 여기에 저장된 메시지들을 각 파티션에 쓰여진 대로 읽어온다. 또한 offset을 기록함으로써 어느 메세지까지 읽었는지를 유지한다. 여기서 offset은 메시지를 저장할 때 메시지에 부여해주는 메타데이터이고 파티션 내에서 메시지의 순서를 나타내는 고유 번호이다. 또한 컨슈머는 컨슈머 그룹의 일원으로서 작동한다. 컨슈머 그룹은 토픽에 저장된 데이터를 읽어오기 위한 하나이상의 컨슈머이다. 이는 각 파티션이 하나의 컨슈머에 의해서만 읽히도록 하고 컨슈머에서 파티션으로의 대응관계를 소유권이라고 한다. 브로커와 클러스터 하나의 카프커 서버를 브로커라 부른다. 브로커는 프로듀서로부터 메시지를 받아 오프셋을 할당한 뒤 디스크 저장소에 쓴다. 브로커는 컨슈머의 파티션 읽기 요청 역시 처리하고 발행한 뒤의 메시지를 보내준다. 하나의 브로커는 초당 수천 개의 파티션과 수백만 개의 메시지를 처리하는 것이 가능하다. 카프카 브로커는 클러스터의 일부로 작동한다. 하나의 클러스터 안에 여러 개의 브로커가 포함될 수 있고 하나의 브로커가 클러스터 컨트롤러 역할을 하게 된다. 이때 컨트롤러의 역할 파티션을 브로커에 할당 장애가 발생한 브로커를 모니터링하는 관리기능 수행 파티션은 클러스터 안의 브로커가 담당하고 이를 파티션 리더라고 한다. 복제된 파티션에는 여러 브로커가 할당 가능한데 이를 파티션의 팔로워라고 한다. kafka는 RabbitMQ와 달리 Consumer가 읽었다고 해서 메시지가 삭제되지 않는다. 또한 카프카의 핵심기능 중 하나로 메시지를 지속성 있게 보관하는 보존(retention)기능이 있다. 특정 기간, 특정 사이즈가 될 때까지 보관하고 한도값에 도달하면 메세지는 만료되어 사라진다. 사용자 활동 추적 토픽, 애플리케이션 지표 등 목적에 맞게 보존 설정을 하면 된다. 다중 클러스터 장점 데이터 유형별 분리 보안 요구사항을 충족 시키기 위한 격리 재해 복구를 대비한 다중 데이터 센터 카프카 프로젝트는 데이터를 다른 클러스터로 복제하는데 사용되는 미러데이터라는 툴을 포함한다. Kafka가 대규모 서비스에서 선택되는 이유 자연스럽게 여러 프로듀서를 처리할 수 있다. 많은 프론트엔드 시스템으로부터 데이터를 수집하고 일관성을 유지하기 좋다. 많은 컨슈머가 상호 간섭 없이 어떠한 메시지 스트림을 읽는 것이 가능하다. 컨슈머들이 항상 실시간으로 데이터를 읽어올 필요가 없다. 다른 메시지 스트림들이 각종 트래픽 폭주, 느린 처리 속도와 같은 사항에도 데이터 유실의 위험은 없다. 전체의 가용성에 영향을 주지 않으면서 확장이 가능하다. kafka 로컬에 도입하기 지금 내가 보고있는 카프카 핵심가이드 기준으로는 kafka가 3.x.x 버전이라서 apache zoo-keeper를 도입하고 카프카를 설치하여 두개를 사용하는 구조이지만 kafka 4.0부터 kRaft라고 zoo-keeper 없이 kafka의 이미지로만 실행하는 것이 가능하다. services: kafka: image: apache/kafka:4.3.1 container_name: kafka ports: - "9092:9092" volumes: - kafka-data:/var/lib/kafka/data restart: unless-stopped volumes: kafka-data: 이런 식으로 docker compose 파일을 만들어주고 kafka를 실행한다. docker exec -it kafka bash 명령어를 사용하여 카프카에 접속을 한 뒤 cd /opt/kafka/bin를 통해 이동해주고 실습을 진행하게 된다. 토픽 생성 ./kafka-topics.sh \ –bootstrap-server localhost:9092 \ –create \ –topic study-topic \ –partitions 1 \ –replication-factor 1 복재 개수 하나, 토픽 하나, 파티션 하나로 해서 기본적인 토픽을 만들어준다. 프로듀서로 메시지 전송 ./kafka-console-producer.sh \ –bootstrap-server localhost:9092 \ –topic study-topic 여기서 메시지를 입력하고 ctrl+ c로 종료하여 메시지를 전달한다. 컨슈머로 메시지 읽기 ./kafka-console-consumer.sh \ –bootstrap-server localhost:9092 \ –topic study-topic \ –from-beginning –from beginning으로 처음부터 메시지를 읽게 된다. producer -> kafka 저장 -> consumer에서 kafka 조회 이러한 순서로 받아드리게 된다. 기존 zoo-keeper의 역할 기존 zoo-keeper이 한 일 Kafka 브로커 등록과 상태 관리 컨트롤러 선출 지원 토픽 및 파티션 메타데이터 관리 파티션 리더 정보 관리 일부 설정 정보 보관 지금은 KRaft에서 Kafka가 자체 Raft 기반 메타 데이터 쿼럼을 사용한다. Kafka Controller Quorum라는 클러스터 메타데이터를 자체적으로 관리하는 프로토콜을 사용하여 활성 컨트롤러를 선출한다.

백엔드 · 2026-07-19

Spring Boot Actuator와 Prometheus로 애플리케이션 관찰하기

관찰 가능성이 필요한 이유 MSA에서는 요청이 서비스 A에서 B와 C로 이어질 수 있다. 이때 요청이 어느 서비스와 프로세스를 거쳤는지 추적할 수 있어야 한다. 분산 추적에는 OpenTelemetry와 Zipkin을 사용할 수 있고, 애플리케이션 상태와 JVM 지표를 수집할 때는 Spring Boot Actuator와 Prometheus를 사용할 수 있다. Spring Boot Actuator Actuator는 애플리케이션의 운영 정보를 엔드포인트로 제공한다. health 엔드포인트에서는 서버가 정상적으로 동작하는지 확인할 수 있다. Blue-Green 배포에서도 새 환경이 준비되었는지 검사하는 데 이 상태 정보가 필요하다. Actuator는 CPU와 JVM처럼 민감할 수 있는 운영 정보도 다루므로 외부에 그대로 공개하지 않아야 한다. 필요한 엔드포인트만 제한적으로 노출하고 접근을 보호해야 한다. Swagger, Kibana, Grafana 같은 운영 도구도 외부에 직접 노출하지 않는 편이 좋다. Prometheus로 메트릭 수집하기 Prometheus는 시계열 데이터를 저장하고 조회하며, 지정한 엔드포인트에서 메트릭을 주기적으로 가져온다. 수집 주기를 지나치게 짧게 잡으면 대상 애플리케이션에 부담을 줄 수 있다. scrape_configs: - job_name: "service-a" scrape_interval: 15s metrics_path: /actuator/prometheus static_configs: - targets: ["host.docker.internal:8080"] Prometheus를 컨테이너에서 실행할 때 localhost는 호스트가 아니라 해당 컨테이너의 127.0.0.1을 가리킨다. 호스트에서 실행 중인 애플리케이션을 수집하려면 환경에 맞는 호스트 주소를 사용해야 한다. 같은 Docker Compose 네트워크에서 실행한다면 서비스 이름으로 접근할 수 있다. JVM 힙 메모리 사용 비율은 다음과 같은 PromQL로 계산할 수 있다. sum(jvm_memory_used_bytes{area="heap"}) by (instance) / sum(jvm_memory_max_bytes{area="heap"}) by (instance) Grafana 대시보드 연결 메트릭을 확인할 때마다 PromQL을 직접 입력하는 대신 Grafana 대시보드로 시각화할 수 있다. Docker Compose로 Prometheus와 Grafana를 함께 실행한다면 Grafana 데이터 소스에 같은 네트워크의 Prometheus 서비스 주소를 등록한다. http://prometheus:9090 패널을 직접 구성하거나 공개된 Grafana 대시보드 템플릿에서 시작할 수 있다. 학습 당시 확인한 Spring 관련 템플릿의 ID는 11892였다. Docker Compose의 depends_on은 컨테이너 시작 순서를 표현할 수 있지만 애플리케이션이 실제 요청을 받을 준비가 끝났다는 것까지 보장하지는 않는다. 준비 상태까지 확인하려면 health check를 함께 설계해야 한다. 배운 점 운영 상태를 파악하기에는 로그만으로 부족하다. Actuator가 애플리케이션 상태와 메트릭을 노출하고, Prometheus가 이를 수집하며, Grafana가 조회 결과를 대시보드로 보여주는 구조를 만들 수 있다. 운영 엔드포인트와 대시보드에는 민감한 정보가 포함될 수 있으므로 접근 제어가 필요하다. 컨테이너 환경에서는 localhost의 의미와 서비스 준비 상태도 별도로 고려해야 한다.

백엔드 · 2026-06-23

docker, AWS, github action을 활용한 배포

서론 난이도로 따지면 동적배포보다는 정적배포가 쉽다고 볼 수가 있다. 하지만 우리가 구축하는 대다수의 프로그램들은 데이터베이스와 통신하는 어플리케이션이기 때문에 동적배포가 필요하다고 볼 수가 있다. 저번에 내가 정적배포를 시도하다가 만났던 Unable to determine Dialect without JDBC metadata 와 같은 오류는 DB연결에서 발생하는 오류도 사실상 동적배포의 영역에서 만나는 오류라고 볼 수가 있다. 브라우저 -> (Http) -> Spring boot -> (JDBC) -> MySQL 이러한 과정으로 접근을 하게 되는데 사용자의 요청에 따라 결과가 달라지게 되므로 정적은 이미 만들어진 (정적인) html, css, js 파일을 클라이언트에게 제공하는 것이라고 볼 수가 있고 동적 웹은 직접 html,css, js를 만들어서 클라이언트에게 던져주는 것이다. github action으로 배포관리 해주기 github action은 github에서 제공해주는 ci/cd (지속적 통합/ 지속적 배포) 자동화 도구이다. 다른 말로 코드가 변경되면 미리 정의한 작업을 자동으로 실행해주는 시스템이다. 이전에는 개발자가 직접 (코드 작성 -> git push -> 서버 접속 -> 테스트 실행 -> 빌드 -> 배포)까지의 일을 반복했어야 했다. 문제는 테스트를 깜빡하고, 빌드 확인을 안하고, 실수 등이 발생가능 하다. github actions의 원리 name: CI on: push: branches: - main env: REGISTRY: ghcr.io 와 같은 코드가 있다면 의미는 main 브랜치에 push가 발생한다면 github 이벤트가 발생 -> Action 실행이라는 흐름을 의미한다. Developer ↓ git push GitHub Repository ↓ 이벤트 감지 GitHub Runner ↓ Workflow 실행 ghcr.io GitHub Container Registry에 업로드를 하는 것을 의미한다. Github Runner github actions에서 설정한 ci/cd 워크플로우를 실행하는 가상 머신 또는 서버 컴퓨터를 의미한다. runs-on: ubuntu:latest github에서 제공하는 ubuntu VM이 생성되고 실행을 하게 된다. Ci를 위한 워크플로 설정 name: ci-workflow.yml on: pull_request: branches: - dev - main jobs: code-test: name: 코드 테스트 runs-on: ubuntu-latest steps: - name: 브랜치로 체크아웃 uses: actions/checkout@v6 - name: JDK 설치 uses: actions/setup-java@v5 with: distribution: 'temurin' java-version: 25 - name: gradlew 권한 세팅 run: chmod +x ./gradlew - name: 태스트 실행 run: ./gradlew test --no-daemon .github에 이렇게 ci를 위한 기능을 추가했다. 만약 실행순서를 보장하고 싶다면 needs:에 실행하고 싶은 job을 기록하면 될 것 같다. release를 위한 워크플로 파일 설정 name: Build and release docker image on: push: branches: # - master - dev env: REGISTRY: ghcr.io jobs: build-image: name: 도커 이미지 빌드 runs-on: ubuntu-latest # needs: tagging permissions: contents: read packages: write attestations: write id-token: write steps: - name: 리포지터리로 체크아웃 uses: actions/checkout@v6 - name: JDK 세팅 uses: actions/setup-java@v5 with: distribution: 'temurin' java-version: '25' - name: gradlew 권한세팅 run: chmod +x ./gradlew - name: Gradle 빌드 run: ./gradlew build -x test - name: 레지스트리에 로그인 uses: docker/login-action@v4 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: 메타데이터 추출 id: meta uses: docker/metadata-action@v6 with: images: ${{ env.REGISTRY }}/${{ github.repository }} tags: | type=sha type=raw,value=latest - name: 빌드 및 이미지 푸시 uses: docker/build-push-action@v7 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} github secrets 설정 github actions는 docker hub 로그인, EC2 서버 접속 등 배포 과정에서 민감한 정보를 사용해야 한다. Docker Hub 아이디, EC2 SSH Private Key, 데이터베이스 비밀번호 등 workflow 파일에 작성되면 노출될 위험이 있다. 이러한 정보는 github secrets로 보관하는 편이 좋다. github runners 설정 github runners의 self-hosted 서버를 사용할 때 settings에 runners에 들어가서 새로운 new self-hosted runner을 구축해줘야 한다. runner를 만들어주면 os에 따라 다른 코드가 나오는데 이를 연결하는 가상머신에 입력해주면 된다.

백엔드 · 2026-06-21

GitHub Actions로 시작하는 CI 파이프라인

CI가 필요한 이유 Pull Request 화면에서는 코드 변경점을 확인할 수 있지만 개발 환경의 차이까지 비교하기는 어렵다. 변경 파일이 많으면 사람이 모든 내용을 확인하는 데에도 시간이 많이 든다. 여러 개발자의 코드를 하나로 합칠 때 빌드와 테스트를 자동으로 실행하면 문제가 있는지 빠르게 확인할 수 있다. GitHub Actions는 GitHub에서 발생하는 push, pull_request, release 등의 이벤트를 기준으로 작업을 실행한다. 저장소의 .github/workflows 디렉터리에 YAML 파일을 두면 정의한 절차대로 워크플로가 실행된다. 워크플로 구성 요소 워크플로에는 job과 step이 있다. job은 하나의 작업 단위이며 기본적으로 서로 병렬 실행된다. step은 한 job 안에서 순서대로 실행되는 세부 과정이다. 작업 사이에 의존 관계를 설정하면 앞 작업의 결과를 다음 작업의 입력으로 연결할 수 있다. on에는 워크플로를 시작할 이벤트를 정의한다. runs-on에는 작업이 실행될 환경을 지정한다. 외부 시스템이 GitHub 이벤트를 받아 작업해야 한다면 Webhook을 이용할 수 있다. 특정 이벤트가 발생하면 지정한 URL로 JSON 데이터를 전송하며, Slack 알림이나 Jenkins 기반 배포 같은 흐름에 활용할 수 있다. Spring 프로젝트 테스트 워크플로 GitHub가 제공하는 실행 환경에는 저장소의 소스 코드와 프로젝트에 필요한 JDK가 자동으로 준비되어 있지 않다. 따라서 저장소 체크아웃, JDK 설치, Gradle 테스트를 각각 step으로 정의한다. name: ci-workflow on: pull_request: jobs: code-test: name: 코드 테스트 runs-on: ubuntu-latest steps: - name: 브랜치 체크아웃 uses: actions/checkout@v6 - name: JDK 설치 uses: actions/setup-java@v5 with: distribution: "temurin" java-version: "25" - name: 테스트 실행 run: ./gradlew test --no-daemon Linux 실행 환경에서 gradlew에 실행 권한이 없다면 권한을 부여하는 step이 추가로 필요할 수 있다. - name: Gradle Wrapper 실행 권한 부여 run: chmod +x gradlew 배운 점 CI는 Pull Request에 올라온 코드를 사람이 읽는 작업을 대체하지 않는다. 반복 가능한 빌드와 테스트를 자동으로 수행해 통합 위험을 일찍 드러내는 장치다. GitHub Actions에서는 이벤트, job, step과 실행 환경의 관계를 이해해야 한다. 워크플로를 작성할 때는 소스 코드 체크아웃, JDK 준비, 실행 권한과 테스트 명령까지 실행 환경 관점에서 빠짐없이 정의해야 한다.

백엔드 · 2026-06-12

동현의 나불나불

Contact

백엔드