Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

Hook이란?

Hook은 Claude Code가 도구(Read, Write, Grep 등)를 실행하기 전 또는 후에 특정 커맨드를 자동으로 실행할 수 있게 해주는 기능입니다.

두 가지 종류가 있습니다.

Hook 설정

Hook은 Claude settings 파일에 정의하며, 범위에 따라 아래 세 경로 중 하나에 추가합니다.

직접 파일에 작성하거나, Claude Code에서 /hooks 명령어로도 입력할 수 있습니다.

설정 예시는 아래와 같습니다.

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "node /home/hooks/read_hook.ts"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "node /home/hooks/edit_hook.ts"
          }
        ]
      }
    ]
  }
}

Hook 정의하기

Hook을 정의하는 과정은 아래 순서로 진행합니다.

1. PreToolUse / PostToolUse 중 사용할 Hook 결정
2. 어떤 Tool에 대해 설정할지 결정
3. Tool 호출 시 실행할 커맨드를 settings.json에 등록
4. 필요 시, 커맨드 결과로 Claude에게 피드백 제공
   • exit 0 → 정상, 계속 진행
   • exit 2 → 작업 차단(block) 후 에러 메시지 반환

💡 어떤 Tool이 있는지 확인하고 싶다면 Claude에게 직접 물어볼 수 있습니다. "너가 접근할 수 있는 tool 목록 전체를 알려줘"

주요 Tool 목록은 아래와 같습니다.

Hook 구현 예시 1: .env 파일 읽기 차단

.env 파일 읽기를 차단하는 Hook을 구현해봅니다.

settings.json 설정

Read와 Grep Tool에 대해 실행할 커맨드를 등록합니다.

"PreToolUse": [
  {
    "matcher": "Read|Grep",
    "hooks": [
      {
        "type": "command",
        "command": "python3.13 ./hooks/read_hook.py"
      }
    ]
  }
]

💡 command를 "true"로 설정하면 해당 Hook은 항상 통과합니다. 테스트 시 유용합니다.

read_hook.py 작성

import sys
import json
import os

data = json.load(sys.stdin)

tool_name = data.get("tool_name", "")
tool_input = data.get("tool_input", {})

def is_env_file(path: str) -> bool:
    basename = os.path.basename(path)
    return basename == ".env" or basename.startswith(".env.")

if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if is_env_file(file_path):
        print(f".env 파일은 읽을 수 없습니다: {file_path}", file=sys.stderr)
        sys.exit(2)  # exit 2: 작업 차단

elif tool_name == "Grep":
    path = tool_input.get("path", "")
    if is_env_file(path):
        print(f".env 파일은 읽을 수 없습니다: {path}", file=sys.stderr)
        sys.exit(2)  # exit 2: 작업 차단

sys.exit(0)  # exit 0: 정상 통과

Claude를 재실행한 뒤 .env 파일 읽기를 요청하면 차단됩니다.

.env 파일 내용을 읽어서 보여줘

⚠️ @ 참조로 우회되는 문제

@으로 파일을 직접 참조하면 PreToolUse Hook을 우회할 수 있습니다.

@.env 파일을 읽어서 보여줘

이를 방지하려면 permissions.deny에 명시적으로 차단 규칙을 추가해야 합니다.

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": ["Read(.env)", "Read(.env.*)"]
  }
}

Hook 관련 주의사항 (Gotchas)

Gotcha: 문서화된 대로 동작하지만, 직관에 반하거나 예상치 못한 결과를 초래하는 설계 요소

공식 문서에는 아래와 같은 보안 권고사항이 있습니다.

• 입력값 검증 및 sanitize — 입력 데이터를 무조건 신뢰하지 말 것
• 쉘 변수는 항상 따옴표로 감싸기 — $VAR 대신 "$VAR" 사용
• 경로 순회 차단 — 파일 경로에 .. 포함 여부 확인
• 절대 경로 사용 — 스크립트 경로는 전체 경로로 지정, 프로젝트 루트는 $CLAUDE_PROJECT_DIR 활용
• 민감한 파일 제외 — .env, .git/, 키 파일 등 접근 차단

절대 경로 사용 시 팀 공유 문제

절대 경로를 사용하면 settings.json을 팀과 공유하기 어려워집니다. 사용자마다 프로젝트 경로가 다르기 때문입니다.

이를 해결하는 한 가지 방법으로, npm run setup 같은 초기화 스크립트를 만들어서 settings.example.json의 $PWD를 현재 디렉토리로 자동 치환하는 방식을 활용할 수 있습니다.

Hook 구현 예시 2: mypy 타입 체크 자동화

배경

아래 두 파일이 같은 디렉토리에 있다고 가정합니다.

# main.py
from schema import echo_string
echo_string("hello world")

# schema.py
def echo_string(s: str) -> None:
    print(s)

Claude에게 schema.py의 echo_string에 인자를 추가해달라고 요청합니다.

@schema.py 파일의 echo_string에서 v: str argument를 추가해줘

Claude는 schema.py는 잘 수정하지만, main.py의 호출부는 수정하지 않습니다.

# schema.py (수정 후)
def echo_string(s: str, v: str) -> None:
    print(s)

# main.py (수정 안 됨 — 인자 1개만 전달 중)
echo_string("hello world")

이런 타입 불일치는 Python의 mypy로 감지할 수 있습니다.

mypy main.py
main.py:3: error: Missing positional argument "v" in call to "echo_string" [call-arg]
Found 1 error in 1 file (checked 1 source file)

참고: Python 타입 체커 비교

도구	만든 곳	특징
mypy	Python 재단	가장 표준적, CI에서 많이 사용
pyright	Microsoft	VSCode에 내장, 빠르고 엄격
pylance	Microsoft	pyright 기반 VSCode 확장
pytype	Google	타입 힌트 없어도 추론 가능

Python은 타입 힌트가 선택사항이라 강제되지 않습니다. mypy가 체크하려면 타입 힌트가 있어야 하며, 엄격하게 적용하려면 --strict 옵션이나 pyproject.toml에 strict 모드를 설정하는 것이 일반적입니다.

Hook 설정

Python 파일이 수정될 때마다 자동으로 mypy를 실행하는 Hook을 추가합니다.

settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/pycheck",
            "statusMessage": "Running mypy type check..."
          }
        ]
      }
    ]
  }
}

pycheck 스크립트

#!/bin/bash
# pycheck: mypy type checker hook for Claude Code
# Python 파일이 수정될 때마다 mypy를 실행해 타입 오류를 Claude에게 피드백합니다.

STDIN=$(cat)
FILE=$(echo "$STDIN" | jq -r '.tool_input.file_path // empty')

# .py 파일이 아니면 통과
if [[ "$FILE" != *.py ]]; then
  exit 0
fi

# 가상환경이 있으면 활성화
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
if [ -f "$PROJECT_ROOT/venv/bin/activate" ]; then
  source "$PROJECT_ROOT/venv/bin/activate"
fi

# 프로젝트 전체에 mypy 실행 (호출부 오류까지 감지)
MYPY_OUTPUT=$(mypy "$PROJECT_ROOT" --ignore-missing-imports 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  # Claude에게 타입 오류를 피드백으로 전달
  jq -n \
    --arg output "$MYPY_OUTPUT" \
    --arg file "$FILE" \
    '{
      "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": ("mypy found type errors in " + $file + ":\n" + $output + "\n\nPlease fix the type errors above.")
      }
    }'
fi

다시 인자 추가를 요청하면, 이번에는 Claude가 main.py의 호출부도 함께 수정합니다.

추가로 알아두면 유용한 Hook 종류

강의에서 다룬 PreToolUse와 PostToolUse 외에도 아래와 같은 Hook이 존재합니다.

Hook 입력값(stdin) 구조 주의사항

Hook을 작성할 때 한 가지 헷갈리는 점이 있습니다.

커맨드로 전달되는 stdin 입력값의 구조가 Hook 종류와 matcher에 따라 달라집니다.

예를 들어, TodoWrite Tool이 호출된 후 실행되는 PostToolUse Hook의 stdin은 아래와 같습니다.

{
  "session_id": "9ecf22fa-edf8-4332-ae85-b6d5456eda64",
  "transcript_path": "",
  "hook_event_name": "PostToolUse",
  "tool_name": "TodoWrite",
  "tool_input": {
    "todos": [{ "content": "write a readme", "status": "pending", "priority": "medium", "id": "1" }]
  },
  "tool_response": {
    "oldTodos": [],
    "newTodos": [{ "content": "write a readme", "status": "pending", "priority": "medium", "id": "1" }]
  }
}

반면, Stop Hook의 stdin은 훨씬 단순합니다.

{
  "session_id": "af9f50b6-f042-4773-b3e2-c3a4814765ce",
  "transcript_path": "",
  "hook_event_name": "Stop",
  "stop_hook_active": false
}

이처럼 Hook 종류와 matcher가 달라지면 stdin 구조도 크게 달라지기 때문에, 커맨드 스크립트를 작성하기 전에 실제로 어떤 데이터가 들어오는지 먼저 확인하는 것이 중요합니다.

stdin 구조 확인하는 방법

아래와 같이 stdin을 파일로 저장하는 헬퍼 Hook을 먼저 등록해두면, 실제 어떤 데이터가 들어오는지 쉽게 확인할 수 있습니다.

"PostToolUse": [
  {
    "matcher": "*",
    "hooks": [
      {
        "type": "command",
        "command": "jq . > post-log.json"
      }
    ]
  }
]

matcher를 *로 설정해 모든 Tool 호출을 잡고, stdin을 post-log.json에 저장합니다. Hook을 실제로 실행해보면 post-log.json에 기록된 데이터를 보고 스크립트에서 어떤 필드를 참조해야 하는지 파악할 수 있습니다.

💡 PreToolUse, Stop 등 다른 Hook 종류도 동일한 방법으로 확인할 수 있습니다. 스크립트를 작성하기 전에 이 헬퍼 Hook으로 구조를 먼저 파악하는 습관을 들이면 디버깅 시간을 크게 줄일 수 있습니다.

전체 정리

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

Github Integration

github repo에 claude를 연동해서 mention이나 PR review를 하도록 통합할 수 있습니다. 현재 구독중인 Plan과 별도로 API 사용 비용이 청구되며 Claude Code Review와는 별도 기능입니다.

Claude Code Review (별도 관리형 서비스) Anthropic이 최근 출시한 Code Review는 리뷰당 평균 $15~25가 청구되며, PR 크기와 코드베이스 복잡도에 따라 달라집니다. 이 비용은 플랜에 포함된 사용량과 별도로 extra usage로 청구됩니다. Claude 그리고 Code Review는 현재 Team 및 Enterprise 플랜에서만 research preview로 사용 가능합니다. Claude Pro 플랜에서는 이 기능을 쓸 수 없습니다.

연동 및 사용방법

claude를 실행 후, /install-github-app을 입력하면 연동을 진행할 수 있으며, claude code API Key가 필요합니다.

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

MCP(Model Context Protocol) Server란?

MCP Server를 추가하면 Claude Code의 기능을 확장할 수 있습니다. 추가한 서버는 로컬 또는 원격(remote)으로 실행할 수 있으며, Claude가 기본적으로 수행할 수 없는 작업(브라우저 제어, 외부 서비스 연동 등)을 가능하게 합니다.

Playwright MCP Server 설치하기

Claude 실행 전, 터미널에서 아래 명령어로 MCP Server를 추가합니다.

claude mcp add playwright npx @playwright/mcp@latest

이후 Claude를 실행합니다.

claude

💡 Playwright MCP는 Claude가 실제 브라우저를 열고 조작할 수 있게 해주는 서버입니다. E2E 테스트나 UI 검증 작업을 자동화할 때 유용합니다.

MCP Server 권한 설정하기

MCP Server가 실행되면 필요한 권한 허용을 요청합니다. 매번 승인하는 과정을 생략하려면 .claude/settings.local.json에 아래와 같이 권한을 미리 설정할 수 있습니다. 서버명은 언더바 두 개(__)를 구분자로 사용합니다.

{
  "permissions": {
    "allow": ["mcp__playwright"],
    "deny": []
  }
}

설정 후 Claude를 재시작하면 이후 실행부터는 권한 요청 없이 바로 동작합니다.

MCP Server 사용해보기: 브라우저 자동화

Claude를 실행한 뒤 아래와 같이 입력하면 실제 브라우저가 열리고 localhost:5173으로 이동합니다.

open a browser and navigate to localhost:5173

이 상태에서 아래와 같이 요청하면, Claude가 직접 브라우저를 조작하며 작업을 수행합니다.

제목이 'TODO 6'인 티켓을 하나 만들고, 생성된 티켓이 'IN PROGRESS', 'DONE'으로
상태 변경이 잘 되는지 확인해. 마지막에는 'TO DO'의 최상단으로 옮겨.

ESC로 추가 정보 제공하기

작업 중 Claude가 잘못된 방법으로 접근하는 경우, ESC로 작업을 중단하고 올바른 방법을 알려줄 수 있습니다.

이번 예시에서는 Claude가 티켓 상세 화면에서 상태를 변경하려 했지만, 실제로는 보드 화면에서 드래그로만 상태 변경이 가능했습니다.

ESC로 중단한 뒤 아래와 같이 정보를 추가로 제공했습니다.

보드 화면에서 티켓을 드래그해서 옮길 수 있어.

이후 Claude는 드래그 방식으로 정상적으로 티켓을 이동하며 테스트를 완료했습니다.

💡 Claude가 막히는 상황에서 ESC로 중단하고 힌트를 주는 패턴은 이전 포스팅의 ESC + Memory 활용법과도 연결됩니다. 반복되는 상황이라면 CLAUDE.md에 등록해두는 것을 고려해보세요.

정리

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

Custom Command란?

자주 반복하는 작업을 마크다운 파일로 정의해두면, /커맨드명 형태로 빠르게 실행할 수 있습니다. 매번 긴 지시문을 입력할 필요 없이, 커맨드 한 줄로 동일한 작업을 재현할 수 있는 것이 핵심입니다.

Custom Command 만들기

.claude/commands/ 경로에 커맨드로 사용할 마크다운 파일을 생성합니다. 파일명이 곧 커맨드명이 되며, 생성 후에는 Claude를 재시작해야 적용됩니다.

예를 들어 audit.md를 생성하면 /audit으로 실행할 수 있습니다.

재시작 후 /audit을 입력하면 정의한 작업이 실행됩니다.

$ARGUMENTS로 동적 입력 받기

커맨드 실행 시 인자를 전달하고 싶다면 파일 내용에 $ARGUMENTS를 추가하면 됩니다.

예를 들어 .claude/commands/summary_file.md를 아래와 같이 작성합니다.

Show me the summary for: $ARGUMENTS
Showing conventions:

Place summary file in a summary directory in the same folder as the source file
Name files as [filename].summary

실행할 때는 커맨드 뒤에 원하는 인자를 붙여서 입력합니다. /summary_file the files in @src/ directory.

💡 $ARGUMENTS에는 파일 경로뿐만 아니라 어떤 텍스트든 전달할 수 있습니다. @파일명 형태로 특정 파일을 참조하는 것도 가능합니다.

정리

시리즈 #1, #2, #3에서 다룬 내용을 명령어 중심으로 재정리한 글입니다.

📁 프로젝트 초기화

/init

새 프로젝트에서 처음 실행하는 명령어. 코드베이스 전체를 분석하고 CLAUDE.md 파일을 자동으로 생성한다.

/init

📝 컨텍스트 & 메모리 관리

# — Memory Mode

#으로 시작하는 입력은 CLAUDE.md에 영구적으로 저장된다. 매번 반복해서 지시하지 않아도 Claude가 항상 해당 규칙을 따르게 된다.

# Use comments sparingly. Only comment complex code.

# The database schema is defined in the @prisma/schema.prisma file.
  Reference it anytime you need to understand the structure of data stored in the database.

@ — 파일 참조

@파일명으로 특정 파일을 직접 멘션한다. Claude가 파일을 탐색하는 시간 없이 즉시 해당 파일을 기반으로 답변한다.

How does the auth system work? @src/auth/middleware.ts

⚙️ 실행 모드

Shift + Tab × 2 — Planning Mode

코드를 바로 수정하지 않고 실행 계획을 먼저 수립한다. 사용자의 승인 후 실제 작업을 진행한다.

• 여러 파일에 걸친 리팩토링처럼 넓은 범위를 탐색해야 할 때 적합
• 여러 단계를 순서대로 진행해야 하는 작업에 유리

Think 키워드 — Thinking Mode

프롬프트에 키워드를 포함하면 Claude가 더 깊이 추론한 뒤 답변한다. Planning Mode와 함께 사용할 수 있다.

This is a tough task, so ultrathink about the best way to implement it.

• 특정 로직 분석, 재현이 어려운 버그 추적처럼 깊이 있는 분석이 필요할 때 적합

⚠️ Planning Mode와 Thinking Mode 모두 일반 요청보다 토큰을 더 많이 소비한다. API를 직접 사용하는 경우 비용이 증가할 수 있으므로 꼭 필요한 상황에서만 사용하자.

🛑 작업 제어

ESC — 작업 중단

진행 중인 작업을 즉시 중단한다. 이후 범위를 좁혀서 다시 요청하거나, continue로 이어서 진행할 수 있다.

# ESC로 중단 후 범위를 좁혀 재요청
Write tests for the createSession function

# 또는 # 으로 CLAUDE.md 수정 후 이어서 진행
continue

ESC × 2 — 대화 Rewind (되돌리기)

대화를 특정 시점으로 되돌린다. 디버깅 등으로 대화가 길어졌을 때 불필요한 컨텍스트를 제거하고 새 작업을 깔끔하게 시작할 수 있다.

• 시점 선택 후 이전 입력값이 자동으로 채워짐
• 해당 텍스트를 수정해서 새 요청을 보내면 됨

🧹 컨텍스트 초기화

대화가 길어지면 컨텍스트 윈도우가 가득 차 응답 품질이 저하될 수 있다. 아래 두 명령어로 정리할 수 있다.

/compact

/clear

🔧 커스텀 커맨드

.claude/commands/ — 커스텀 커맨드 등록

.claude/commands/ 경로에 마크다운 파일을 생성하면 /파일명 형태로 실행할 수 있는 커맨드가 된다. 생성 후 Claude를 재시작해야 적용된다.

# .claude/commands/audit.md 생성 후
/audit

$ARGUMENTS — 동적 인자 전달

커맨드 파일 내에 $ARGUMENTS를 삽입하면 실행 시 인자를 동적으로 전달할 수 있다.

# .claude/commands/summary_file.md 내용
Show me the summary for: $ARGUMENTS

#실행 시
/summary_file the files in @src/ directory.

🪝 Hook

/hooks — Hook 설정

Claude Code에서 Hook을 대화형으로 입력하는 명령어. 직접 settings.json을 수정하는 것도 가능하다.

/hooks

Hook 설정 구조 (settings.json)

도구 실행 전후에 커맨드를 자동 실행한다. matcher에 Tool명을 지정하고, |로 여러 Tool을 동시에 지정할 수 있다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [{ "type": "command", "command": "python3 ./hooks/read_hook.py" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [{ "type": "command", "command": "./.claude/hooks/pycheck" }]
      }
    ]
  }
}

permissions.deny — 파일 접근 차단

@ 참조로 Hook이 우회되는 경우를 방지하기 위해 명시적으로 접근을 차단한다.

{
  "permissions": {
    "deny": ["Read(.env)", "Read(.env.*)"]
  }
}

stdin 구조 확인용 헬퍼 Hook

Hook 스크립트 작성 전 실제 stdin 데이터를 파일로 저장해 구조를 파악할 때 사용한다.

{
  "PostToolUse": [
    {
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "jq . > post-log.json" }]
    }
  ]
}

📌 한눈에 보기

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

ESC로 작업 제어하기

작업 중단하기

Write tests for the @src/lib/auth.ts file을 입력하면 Claude는 한 번에 많은 양의 테스트 코드를 작성합니다.

한 번에 하나의 테스트만 작성하게 하고 싶다면, 작업 진행 중에 ESC로 중단할 수 있습니다. 이후 Write tests for the createSession function처럼 범위를 좁혀서 다시 요청하면 됩니다.

ESC + Memory: 반복 에러 방지

작업 중 Claude가 파일 경로를 잘못 인식해서 매번 같은 에러가 반복되는 경우, ESC로 작업을 중단한 뒤 #(memory mode)으로 CLAUDE.md에 올바른 경로나 에러 대응 방법을 정의할 수 있습니다.

이후 continue를 입력하면 수정된 지시사항을 반영해서 작업을 이어갑니다.

💡 일시적인 수정이 아니라, 같은 에러가 다시 발생하지 않도록 CLAUDE.md에 영구적으로 기록하는 것이 핵심입니다.

ESC + ESC: 대화 Rewind(되돌리기)

왜 필요한가?

예를 들어 createSession 함수의 테스트를 작성하는 과정에서 에러가 발생해 디버깅 대화가 길어진 상황을 가정합니다. 디버깅이 완료된 후, 이번엔 getSession 함수의 테스트를 작성하려고 합니다.

그런데 createSession 디버깅 과정의 대화는 getSession 테스트와 아무 관련이 없습니다. 불필요한 컨텍스트가 남아 있으면 Claude가 새 작업을 수행할 때 방해가 될 수 있습니다. 이때 ESC + ESC로 특정 시점의 대화로 되돌아갈 수 있습니다.

사용 방법:

whats in the @src/lib/auth.ts file?을 입력하면 Claude는 아래와 같은 함수 목록을 포함한 결과를 반환합니다.

Functions

createSession(userId: string, email: string)
- Creates a JWT token with 7-day expiration
- Sets an HTTP-only cookie with security flags
- Cookie is secure in production, lax sameSite policy

getSession(): Promise<SessionPayload | null>
- Reads the auth token from cookies
- Verifies and decodes the JWT
- Returns session payload or null if invalid/missing

createSession 함수 테스트를 요청하면 에러가 발생하고,

Claude가 자동으로 디버깅을 진행합니다.

디버깅 과정은 다음과 같이 진행됩니다.

1. 의존성 설치 후 createSession 테스트 실행
2. server-only 모듈 오류 발생 → 테스트 환경에서 모킹하도록 파일 수정
3. 테스트 재실행 및 성공

디버깅이 완료된 후 getSession 테스트로 넘어가려면, 앞서 쌓인 디버깅 대화를 제거해야 합니다. ESC + ESC를 누르면 되돌아갈 시점을 선택할 수 있습니다.

시점을 선택하면 이전 입력값이 입력창에 자동으로 채워지며,

해당 텍스트를 수정해서 새 요청을 보내면 됩니다.

Context 관리 명령어

대화가 길어지면 컨텍스트 윈도우가 가득 차서 Claude의 응답 품질이 저하될 수 있습니다. 이때 아래 두 명령어로 컨텍스트를 정리할 수 있습니다.

/compact

Claude가 학습한 중요 정보(프로젝트 구조, 발견한 버그 등)를 유지하면서 전체 대화 기록을 요약해 컨텍스트 윈도우를 절약합니다.

아래와 같은 상황에서 유용합니다.

• Claude가 프로젝트에 대한 중요한 정보를 파악한 상태일 때
• 관련된 작업을 계속 이어서 진행하고 싶을 때
• 대화가 길어졌지만 중요한 컨텍스트가 포함되어 있을 때

/clear

대화 기록을 완전히 삭제하고 처음부터 시작합니다.

아래와 같은 상황에서 유용합니다.

• 완전히 다른 작업을 시작할 때
• 이전 대화의 맥락이 새 작업에 방해가 될 때
• 깨끗한 상태에서 시작하고 싶을 때

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

이미지로 UI 수정 요청하기

Claude Code는 텍스트뿐만 아니라 이미지(스크린샷)를 붙여넣어 작업을 지시할 수 있습니다. 수정하고 싶은 UI 영역을 스크린샷으로 캡처한 뒤, Claude Code에 붙여넣고 원하는 작업을 설명하면 됩니다.

예시 1: UI 요소 위치 변경

아래 화면에서 빨간 부분만 스크린샷으로 복사한 뒤,

이미지를 붙여넣고 위치 변경을 요청하면,

해당 요소의 위치가 변경되어 적용됩니다.

💡 이처럼 이미지를 활용하면 긴 설명 없이도 Claude에게 정확한 맥락을 전달할 수 있어 작업 지시가 훨씬 빠르고 직관적해집니다.

예시 2: 내부 도구 메시지 개선 + 컴포넌트 분리 + 테스트 작성

Create a card with a title and ad description.을 입력하면, Claude가 파일을 수정할 때 str_replace_editor라는 내부 도구 이름이 그대로 노출됩니다.

이 화면을 캡처해서 아래와 같이 요청하면,

[Image #3] Replace the 'str_replace_editor' text with a more user friendly message 
of what this tool call is doing. For example, maybe state that a file is being 
created or edited, along with the name of the file being modified. 
Also, put this into a new component and write tests for it.

Claude는 두 가지 방법을 제시하며, 컴포넌트 분리와 테스트 작성까지 한 번에 처리합니다.

Planning Mode

Shift + Tab을 두 번 누르면 Planning Mode로 진입할 수 있습니다.

Planning Mode에서 Claude는 바로 코드를 수정하지 않고, 먼저 실행 계획을 수립합니다.

• 프로젝트에서 더 많은 파일을 읽어옴
• 상세한 실행 계획을 생성함
• 정확히 무엇을 할 것인지 보여줌
• 사용자의 승인을 받은 후 진행함

실제로 Planning Mode로 이미지와 함께 아래와 같이 입력하면

[Image #3] Replace the 'str_replace_editor' text with a more user friendly message 
of what this tool call is doing. For example, maybe state that a file is being 
created or edited, along with the name of the file being modified. 
Also, put this into a new component and write tests for it.

Creating App.jsx로 변경된 것을 확인할 수 있습니다.

Thinking Mode

Thinking Mode는 Claude가 답변을 생성하기 전에 내부적으로 더 깊이 추론하도록 유도하는 기능입니다. 특정 키워드를 프롬프트에 포함하는 것만으로 활성화할 수 있으며, Planning Mode와 함께 사용할 수 있습니다.

사용 예시:

This is a tough task, so ultrathink about the best way to implement it.

언제 무엇을 쓸까?

어려운 작업을 수행할 때 두 모드를 적절하게 활성화하면 Claude의 문제 해결 능력을 끌어올릴 수 있습니다.

💡 Planning Mode와 Thinking Mode는 둘 다 독립적으로 실행 가능합니다.

• Thinking Mode만 — 특정 로직이나 버그처럼 깊은 추론이 필요할 때
• Planning Mode만 — 넓은 범위를 탐색하고 실행 계획을 먼저 짜야 할 때
• 둘 다 — 복잡하고 범위도 넓으면서 추론도 깊게 필요한 작업일 때

Planning Mode가 적합한 경우

코드베이스 전체를 파악하고 넓은 범위를 탐색해야 하는 작업에 적합합니다. 예를 들어 여러 파일에 걸친 리팩토링이나, 여러 단계를 순서대로 진행해야 하는 작업이 이에 해당합니다.

BFS(Breadth-First Search)처럼 넓게 먼저 보는 방식의 작업에 유리합니다.

Thinking Mode가 적합한 경우

특정 로직에 집중하거나, 재현이 어려운 버그를 추적할 때처럼 깊이 있는 분석이 필요한 작업에 적합합니다.

⚠️ 주의: 토큰 비용

Planning Mode와 Thinking Mode는 모두 일반 요청보다 더 많은 토큰을 소비합니다. API를 직접 사용하는 경우 비용이 증가할 수 있으므로, 꼭 필요한 상황에서만 활용하는 것을 권장합니다.

Anthropic SkillJar의 Claude Code 강의를 듣고 정리한 내용입니다. https://anthropic.skilljar.com/claude-code-in-action

Claude Code란?

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 어시스턴트입니다. 단순한 코드 자동완성 도구가 아니라, 코드베이스 전체를 이해하고 실제 작업(파일 수정, 명령 실행 등)을 에이전트처럼 수행할 수 있는 것이 특징입니다.

일반적인 코딩 어시스턴트(GitHub Copilot 등)가 제안(suggestion) 중심이라면, Claude Code는 실행(action) 중심입니다.

프로젝트 시작: /init

새 프로젝트에서 Claude Code를 처음 사용할 때는 /init 커맨드부터 시작하는 것을 권장합니다.

1. 코드베이스 전체를 자동으로 분석
2. 구조와 주요 파일을 요약
3. 요약 내용을 CLAUDE.md 파일에 기록

이 과정을 통해 Claude는 이후 모든 요청에서 프로젝트 구조를 다시 파악할 필요 없이 즉시 관련 컨텍스트를 활용할 수 있습니다.

컨텍스트 추가: Adding Context

핵심 원칙: 필요한 것만 제공하라

Claude에게 작업을 시킬 때는 해당 작업과 관련된 파일이나 문서만 제공해야 합니다. 관련 없는 파일까지 넘기면 컨텍스트 윈도우가 낭비되고 노이즈가 늘어나 오히려 성능이 떨어집니다.

CLAUDE.md: Claude의 가이드 문서

/init 실행 시 생성되는 CLAUDE.md는 Claude가 프로젝트를 이해하는 핵심 문서입니다.

CLAUDE.md의 역할

1. 코드베이스 이해 가속화 — 관련 코드를 더 빠르게 찾을 수 있게 함
2. 작업 가이드 제공 — 코딩 스타일, 규칙, 중요 파일 위치 등을 명시

파일 종류별 비교

Custom Instructions: # Memory Mode

#을 입력하면 memory mode가 활성화되어 해당 내용이 CLAUDE.md에 자동으로 추가됩니다.

입력:

# Use comments sparingly. Only comment complex code.

CLAUDE.md에 추가되는 내용:

## Code Style
- Use comments sparingly. Only comment complex code.

이를 통해 대화할 때마다 반복적으로 지시하지 않아도, Claude가 항상 일관된 스타일로 코드를 작성하게 됩니다.

File Mention: @ 파일 참조

질문할 때 @파일명으로 관련 파일을 직접 멘션할 수 있습니다. Claude가 파일을 직접 탐색하는 시간을 줄여주고, 더 빠르고 정확한 답변을 받을 수 있습니다.

예시:

How does the auth system work? @src/auth/middleware.ts

중요 파일을 CLAUDE.md에 등록하기

프로젝트 전반에서 자주 참조되는 파일은 CLAUDE.md에 등록해두면 좋습니다.

예를 들어, Prisma를 사용하는 프로젝트라면 DB 스키마 파일이 거의 모든 기능에 영향을 미칩니다. 이런 파일은 매번 탐색하는 것보다 CLAUDE.md에 명시해두는 것이 효율적입니다.

memory mode로 등록:

# The database schema is defined in the @prisma/schema.prisma file.
  Reference it anytime you need to understand the structure of data stored in the database.

CLAUDE.md에 추가되는 내용:

### Database Schema
Defined in `prisma/schema.prisma`. Reference it whenever you need to 
understand the structure of data stored in the database.

효과 비교

등록 전에는 what attrs does a user have? 같은 질문에 Claude가 파일을 탐색하고 읽는 과정을 거칩니다. 등록 후에는 컨텍스트가 이미 있으므로 즉시 정확한 답변을 반환합니다.

📷 (스크린샷: instruction 없을 때 vs 있을 때 비교)

• 없을 때
• 있을 때

정리

원래라면 AWS EKS에 istio를 설치하고 테스트를 바로 진행하려고 했는데, 로컬에서 테스트하며 정리를 해야할 것 같아서 kind로 생성한 로컬 클러스터에 istio를 설치하고 간단히 동작을 테스트 해보자

참고자료

• 소스코드는 13디렉토리를 참고

  kind로 테스트 진행

  kind로 클러스터 생성

  먼저 아래 yaml 파일을 작성한다. 로컬에서 접근할 것이기 때문에 control plane 노드에 30800 포트를 명시해준다. 이 포트를 이용해 server로 접근할 수 있다. ``` kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes:
• role: control-plane image: kindest/node:v1.33.4 extraPortMappings:

  containerPort는 Kind 노드(컨테이너)의 포트

  이 포트는 Service의 nodePort와 일치

  • containerPort: 30800

    hostPort는 로컬 머신(PC)의 포트

    hostPort: 30800 protocol: TCP
• role: worker image: kindest/node:v1.33.4 labels: role: server
• role: worker image: kindest/node:v1.33.4 labels: role: istiod
• role: worker image: kindest/node:v1.33.4 labels: role: istio-gateway
• role: worker image: kindest/node:v1.33.4 labels: role: istio-gateway

클러스터를 생성한다

kind create cluster --name 1-33 --config cluster.yaml

istio 설치

13/helm 디렉토리에서 helmfile을 이용해 설치한다. 먼저 base를 설치한다.

helmfile sync --selector name=istio-base

다음으로 istiod를 설치한다. nodeSelector에 role=istiod를 명시했다.

helmfile sync --selector name=istio-istiod

다음으로 ingress gateway를 설치한다. 서비스 타입은 NodePort이고 nodeSelector와 affinity를 이용해, 서로 다른 노드에 스케줄링 되도록 했다. (각 노드에 1개씩)

helmfile sync --selector name=istio-gateway

server 파드 배포

server namespace에 배포한다.

kubectl create ns server
kubectl -n server apply -f server.yaml

kube sniff로 트래픽 확인

먼저 server, ingress gateway 이름을 변수로 저장한다.

export SERVER=$(kubectl get pod -n server | grep server | awk '{print $1}')

read GATEWAY1 GATEWAY2 <<< $(kubectl get pods -n istio-system -l istio=gateway -o jsonpath='{.items[*].metadata.name}')
export GATEWAY1 GATEWAY2

sniff로 8000포트 트래픽 기록을 시작한다. 각 파드마다 별도의 터미널에서 실행

kubectl sniff $SERVER -n server -f 'port 8000' --image ghcr.io/nefelim4ag/ksniff-helper:v4 --tcpdump-image ghcr.io/nefelim4ag/tcpdump:latest
kubectl sniff $GATEWAY1 -n istio-system -p -f 'port 8000' --image ghcr.io/nefelim4ag/ksniff-helper:v4 --tcpdump-image ghcr.io/nefelim4ag/tcpdump:latest
kubectl sniff $GATEWAY2 -n istio-system -p -f 'port 8000' --image ghcr.io/nefelim4ag/ksniff-helper:v4 --tcpdump-image ghcr.io/nefelim4ag/tcpdump:latest

로컬에서 python을 이용해 트래픽을 보낸다.

PORT=30800 ENDPOINT="/index" python ./client.py 10

istio ingress gateway 2개 중 1개에만 8000번 포트 트래픽을 확인할 수 있다.

아래는 server 파드의 트래픽이다

istio-system 네임스페이스의 파드 ip 확인 - 10.244.1.5

kubectl get pod -owide -n istio-system          
NAME                             READY   STATUS    RESTARTS   AGE     IP            NODE           NOMINATED NODE   READINESS GATES
istio-gateway-778cbb66c7-l65jd   1/1     Running   0          4h24m   10.244.4.7    1-33-worker3   <none>           <none>
istio-gateway-778cbb66c7-vwr4m   1/1     Running   0          4h24m   10.244.1.5    1-33-worker4   <none>           <none>
istiod-5764bfc-t25wc             1/1     Running   0          4h24m   10.244.3.3    1-33-worker2   <none>           <none>

server 파드의 ip 확인 - 10.244.2.2

kubectl get pod -owide -n server      
NAME                     READY   STATUS    RESTARTS   AGE     IP           NODE          NOMINATED NODE   READINESS GATES
ksniff-9kfzh             1/1     Running   0          40m     10.244.2.3   1-33-worker   <none>           <none>
server-66c6967c6-kjjz5   1/1     Running   0          4h20m   10.244.2.2   1-33-worker   <none>           <none>

docker로 구동중인 kind 클러스터의 노드 ip 확인 172.18.0.6

docker inspect -f '{{.Name}} - {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $(docker ps -q)
/1-33-worker - 172.18.0.5
/1-33-worker4 - 172.18.0.4
/1-33-worker2 - 172.18.0.3
/1-33-worker3 - 172.18.0.2
/1-33-control-plane - 172.18.0.6

client.py를 다시 실행하고 각 파드별로 소켓 연결 상태를 확인하면

// server
root@server-66c6967c6-kjjz5:/app# netstat -antp
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 0.0.0.0:8000            0.0.0.0:*               LISTEN      1/python3.13        
tcp        0      0 10.244.2.2:8000         10.244.1.5:56740        ESTABLISHED 11/python3.13

// istio gateway
istio-proxy@istio-gateway-778cbb66c7-vwr4m:/$ netstat -antp
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name    
tcp        0      0 0.0.0.0:15090           0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 0.0.0.0:15090           0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 0.0.0.0:15021           0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 0.0.0.0:15021           0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 127.0.0.1:15000         0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 0.0.0.0:80              0.0.0.0:*               LISTEN      17/envoy            
tcp        0      0 10.244.1.5:15021        10.244.1.1:54452        TIME_WAIT   -                   
tcp        0      0 10.244.1.5:15021        10.244.1.1:46966        TIME_WAIT   -                   
tcp        0      0 10.244.1.5:52162        10.96.225.207:15012     ESTABLISHED 1/pilot-agent       
tcp        0      0 10.244.1.5:15021        10.244.1.1:50410        TIME_WAIT   -                   
tcp        0      0 10.244.1.5:15021        10.244.1.1:59786        TIME_WAIT   -                   
tcp        0      0 127.0.0.1:48208         127.0.0.1:15020         ESTABLISHED 17/envoy            
tcp        0      0 10.244.1.5:15021        10.244.1.1:33434        TIME_WAIT   -                   
tcp        0      0 10.244.1.5:80           172.18.0.6:3609         ESTABLISHED 17/envoy            
tcp        0      0 127.0.0.1:53688         127.0.0.1:15020         ESTABLISHED 17/envoy            
tcp        0      0 10.244.1.5:56740        10.244.2.2:8000         ESTABLISHED 17/envoy            
tcp6       0      0 :::15020                :::*                    LISTEN      1/pilot-agent       
tcp6       0      0 127.0.0.1:15020         127.0.0.1:48208         ESTABLISHED 1/pilot-agent       
tcp6       0      0 127.0.0.1:15020         127.0.0.1:53688         ESTABLISHED 1/pilot-agent 

연결상태를 정리하면 아래와 같다. localhost:30800 -> control-plane node(172.18.0.6:3609) control-plane node(172.18.0.6:3609) -> istio gateway(10.244.1.5:80) istio gateway(10.244.1.5:56740) -> server(10.244.2.2:8000)

이렇게 연결되어 있는 상태에서, istio gateway를 삭제해보자

kubectl delete pod istio-gateway-778cbb66c7-vwr4m

client 로그는 아래와 같이 삭제 직후 요청이 실패하는 걸 확인할 수 있다.

--- Waiting for 10 seconds... ---
--- Sending keep-alive request #149 (GET /index) ---
--- Received response #149 ---
HTTP/1.1 200 OK

--- Waiting for 10 seconds... ---
--- Sending keep-alive request #150 (GET /index) ---
--- Received response #150 ---
HTTP/1.1 200 OK

--- Waiting for 10 seconds... ---
--- Sending keep-alive request #151 (GET /index) ---

*** TEST FAILED: Server closed connection (recv() returned 0 bytes) ***

*** TEST FAILED: Connection was reset by peer! ***
Error (Code: 54): Connection closed by peer

Socket closed.

패킷을 확인해보면 아래와 같다

• istio gateway
• server

client에서는 현재 graceful하게 종료를 하지 않아서 에러가 발생하지만 istio ingress gateway와 server에서는 FIN 패킷으로 정상 종료된 것을 확인할 수 있다.

요약 및 정리

로컬에서 테스트했을 때, client와 연결된 istio gateway 파드가 client <-> server 사이의 요청을 중개해주는 걸 확인할 수 있다.

istio gateway가 여러 개가 존재해도, 이미 연결되어 있는 client의 경우 연결 에러가 발생할 수 있다. 그래서 keep-alive 연결을 사용하는 client의 경우 retry 로직이 필요하다.

istio에서는 preStop, terminationDrainDuration를 활용할 수 있지만 이 또한 이미 연결된 client에서 retry를 해주는 게 바람직할 것 같다.

AWS에 EKS를 띄우고, aws loadbalancer controller를 설치한 후 alb로 테스트를 진행해보자.

클러스터 만들기

소스코드: 디렉토리 12 참고

eksctl로 클러스터 설치

아래 yaml 파일로

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-cluster
  region: ap-northeast-2
  version: "1.33"

availabilityZones: ["ap-northeast-2a", "ap-northeast-2c"]

vpc:
  clusterEndpoints:
    publicAccess: true  # kubectl exec를 위해 API 서버는 Public에서 접근 허용
    privateAccess: true
  nat:
    gateway: Single

# IAM OIDC 활성화 (LB 컨트롤러 등을 위해 필수)
iam:
  withOIDC: true

managedNodeGroups:
  # 1. Infra Node Group (모니터링, ingress controller 등)
  - name: infra
    instanceType: t3.medium
    minSize: 1
    maxSize: 2
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: infra

  # 2. Server Node Group (백엔드 API 등)
  - name: server
    instanceType: t3.medium
    minSize: 1
    maxSize: 1
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: server

  # 3. Client Node Group (테스트용 클라이언트 등)
  - name: client
    instanceType: t3.medium
    minSize: 1
    maxSize: 1
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: client

eksctl로 클러스터와 노드그룹을 생성한다.

eksctl create cluster -f cluster.yaml --profile kyeongjun-dev

생성이 완료되면 context를 가져온다.

aws eks update-kubeconfig --region ap-northeast-2 --name my-cluster --profile kyeongjun-dev

load balancer controller 설치

curl로 iam policy를 다운로드한 뒤, 생성한다.

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.13.3/docs/install/iam_policy.json

aws --profile kyeongjun-dev iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json

kube-system namespace에 serviceaccount를 생성하고, iam role과 연결한다.

eksctl create iamserviceaccount \
    --cluster=my-cluster \
    --namespace=kube-system \
    --name=aws-load-balancer-controller \
    --attach-policy-arn=arn:aws:iam::<AWS 계정 ID>:policy/AWSLoadBalancerControllerIAMPolicy \
    --override-existing-serviceaccounts \
    --region ap-northeast-2 \
    --approve \
    --profile kyeongjun-dev

helm으로 aws lb controller를 설치한다.

helm install aws-load-balancer-controller eks/aws-load-balancer-controller -f albc-value.yaml -n kube-system

add-on 파드들의 노드 변경하기

kubectl -n kube-system edit deployments.apps metrics-server
kubectl -n kube-system scale deployment metrics-server --replicas 1
kubectl -n kube-system edit deployments.apps coredns
kubectl -n kube-system scale deployment coredns --replicas 1

테스트 환경 만들기

client, server 배포

client, server namespace 생성

kubectl create ns client
kubectl create ns server

12/client.yaml, 12/server.yaml 배포

kubectl apply -f client.yaml -n client
kubectl apply -f server.yaml -n server

아래 그림을 참고하여 tagret group을 aws 콘솔에서 생성한다. nlb 때와 다른 점은 protocol이 HTTP라는 점이다. http여야 alb에 연결할 수 있다.

생성한 target group의 arn을 입력해서 target group binding을 생성한다. (12/tgb.yaml)

kubectl -n server create -f tgb.yaml

ALB 만들기

시리즈 6의 'NLB 만들기'를 참고한다. 여기서 다른 점은, nlb는 az를 하나만 선택할 수 있지만 alb는 2개를 선택해야 한다. 리스터 포트는 80으로 지정했다.

target group의 target이 health가 되면 테스트 환경 세팅 성공이다.

ping-pong 해보기

client 수정해서 ping pong

먼저 alb가 생성됐으니, alb의 private dns 주소를 client.yaml을 수정해준다. 헬스체크도 tcpdump에 잡혀서, /index 경로를 앱에 추가했다.

apiVersion: v1
kind: Service
metadata:
  name: client
  labels:
    app: client
spec:
  ports:
    - port: 80
      targetPort: 80
  selector:
    app: client
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: client
  labels:
    app: client
spec:
  replicas: 1
  selector:
    matchLabels:
      app: client
  template:
    metadata:
      labels:
        app: client
    spec:
      containers:
        - name: client
          image: ghcr.io/kyeongjun-dev/network:dev
          imagePullPolicy: Always
          command: ["sleep", "infinity"]
          env:
            - name: HOST
              value: "internal-server-118699894.ap-northeast-2.elb.amazonaws.com"
            - name: PORT
              value: "80"
            - name: HOST_HEADER
              value: "internal-server-118699894.ap-northeast-2.elb.amazonaws.com"
            - name: USE_TLS
              value: "false"
            - name: ENDPOINT
              value: "/index"
              # value: "/slow?wait=11"
      nodeSelector:
        role: client

client 파드 정보를 저장하고

export CLIENT=$(kubectl get pod -n client | grep client | awk '{print $1}')

간단하게 3초로 테스트 해본다.

kubectl -n client exec -it $CLIENT -- python client.py 3

잘 되는 걸 확인할 수 있다.

설정 값 확인

alb의 기본 Attribute 값을 확인하면 Connection idle timeout이 60초인 것을 확인할 수 있다.

그리고 현재 server(gunicorn)의 --keep-alive는 20초다.

command: ["gunicorn", "--workers", "1", "-k", "gevent", "--bind", "0.0.0.0:8000", "--timeout", "10", "--keep-alive", "20", "app:app", "--log-level", "debug"]

위 값을 고려하면서 server의 --keep-alive 값과 client의 request interval를 조정하며 테스트를 해보자. 현재 interval이 3초일 때는 잘 동작하는 걸 확인했다.

keep alive 20, interval 30

kubectl -n client exec -it $CLIENT -- python client.py 30

3회 정도 요청을 하고 종료했다.

dump 파일에서 Wireshark에 아래와 같이 입력하면 /index 패킷만 확인이 가능하다

http.request.uri contains "/index"

먼저 client 패킷이다. 열어둔 소켓을 이용해 계속 요청을 보내는 걸 확인할 수 있다. (0초, 30초, 60초, 90초)

다음 server 패킷이다. 헬스체크 패킷이 섞여 있어서 각 시간대별로 패킷 스크린샷을 첨부했다.

• 0초
• 30초
• 60초
• 90초

여기서 특이한 점이 있는데, client에서는 기존 연결을 이용해 계속 요청을 보낸다. 그런데 server에서는 --keep-alive 20이 적용되어 있어서 연결을 끊는다. 그런데도 client의 요청은 실패하지 않는다. 패킷 내용을 보면, alb가 client의 요청이 있을 때마다 새롭게 연결을 맺어서 요청을 보내는 걸 확인할 수 있다.

20.xxx초로 요청 부하를 주면, 에러를 재현할 수 있다고 하는데, 재현하지 못했다.

keep alive 20, interval 70

먼저 client 패킷이다. 60초에 alb로부터 client가 FIN 패킷을 받은 걸 확인할 수 있다. - 이를 이용해서 client 앱에서 예외처리를 하면, RST 방지가 가능하다.

다음은 server 패킷이다. 일단 처음에 /index로 GET 요청이 오고, 다음부터는 /index로 요청된 패킷이 없다.

그리고 해당 연결은 20초 후에 제거된다.

여기서도 nlb와의 차이를 알 수 있다. nlb는 idle timeout이 되면 연결 종료(FIN)를 client에게 알리지 않고 제거해버리는데, alb는 client에게 FIN을 전달해서 연결이 종료됨을 알린다.

결과 해석

alb는 어떤 값 설정이 이상적일까?

답은 문서에 나와있기는 하다. 링크

"The target closes the connection with a TCP RST or a TCP FIN message when the load balancer has an outstanding request to the target." The load balancer receives a request and forwards the request to the target. The target starts to process the request, but closes the connection to the load balancer too early. This occurs when the duration of the keep-alive timeout that you configured on the target is shorter than the idle timeout value of the load balancer. Make sure that the duration of the keep-alive timeout is longer than the idle timeout value.

해당 글에서는 server의 keep alive < alb의 idle timeout일 때도 문제가 발생하지는 않았다. 그래도 생각해보면 alb는 연결을 종료할 때, client에 FIN을 보내서 연결이 종료됨을 알리기 때문에 반대가 되어야 하는 게 맞다.

다음 글에서는

이렇게 client > load balancer > server로 이어지는 구조면 좋겠지만, k8s 환경에서는 istio 등 서비스 매시를 쓰는 경우가 많다.

이제 머리가 복잡해져 보자...

AWS에 EKS를 띄우고, aws loadbalancer controller를 설치한 후 nlb로 테스트를 진행해보자.

클러스터 만들기

eks 클러스터 생성 전, kind로 로컬에서 테스트하기 (소스코드 : 레포 09 디렉토리)

kind는 docker desktop을 설치하고, 로컬에서 클러스터를 만들어주는 도구다. 아래 09/cluster.yaml 파일로 클러스터를 생성해보자.

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.33.4
- role: worker
  image: kindest/node:v1.33.4
  labels:
    role: client
- role: worker
  image: kindest/node:v1.33.4
  labels:
    role: server

아래 명령어로 클러스터를 생성했다.

kind create cluster --name 1-33 --config cluster.yaml

node label을 확인해보면 role=client, role=server를 확인할 수 있다.

kubectl get node --show-labels            
NAME                 STATUS   ROLES           AGE    VERSION   LABELS
1-33-control-plane   Ready    control-plane   2m8s   v1.33.4   beta.kubernetes.io/arch=arm64,beta.kubernetes.io/os=linux,kubernetes.io/arch=arm64,kubernetes.io/hostname=1-33-control-plane,kubernetes.io/os=linux,node-role.kubernetes.io/control-plane=,node.kubernetes.io/exclude-from-external-load-balancers=
1-33-worker          Ready    <none>          119s   v1.33.4   beta.kubernetes.io/arch=arm64,beta.kubernetes.io/os=linux,kubernetes.io/arch=arm64,kubernetes.io/hostname=1-33-worker,kubernetes.io/os=linux,role=client
1-33-worker2         Ready    <none>          119s   v1.33.4   beta.kubernetes.io/arch=arm64,beta.kubernetes.io/os=linux,kubernetes.io/arch=arm64,kubernetes.io/hostname=1-33-worker2,kubernetes.io/os=linux,role=server

09/clinet.yaml, 09/server.yaml로 각각 다른 노드에 배포를 진행해보자.

kubectl create ns client
kubectl create ns server

kubectl apply -f client.yaml -n client
kubectl apply -f server.yaml -n server

client 파드 이름을 확인한 후, 명령어를 실행해보면

kubectl -n client exec -it client-578c5494df-brldf -- python client.py 5

요청이 잘 가는 걸 확인할 수 있다. 09/client.yaml파일에 사용한 server.server.svc.cluster.local 주소는 클러스터 내부 도메인이다.

eksctl로 eks 클러스터 만들기

클러스터를 만들었다 지웠다가 하려면 eksctl, terraform 등으로 생성했다가 한번에 지우는 게 비용상으로 유리할 것 같다. 10/cluster.yaml 파일로 eks 클러스터를 생성해보자.

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-cluster
  region: ap-northeast-2
  version: "1.33"

availabilityZones: ["ap-northeast-2a", "ap-northeast-2c"]

vpc:
  clusterEndpoints:
    publicAccess: true  # kubectl exec를 위해 API 서버는 Public에서 접근 허용
    privateAccess: true
  nat:
    gateway: Single

# IAM OIDC 활성화 (LB 컨트롤러 등을 위해 필수)
iam:
  withOIDC: true

managedNodeGroups:
  # 1. Infra Node Group (모니터링, ingress controller 등)
  - name: infra
    instanceType: t3.medium
    minSize: 1
    maxSize: 2
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: infra

  # 2. Server Node Group (백엔드 API 등)
  - name: server
    instanceType: t3.medium
    minSize: 1
    maxSize: 1
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: server

  # 3. Client Node Group (테스트용 클라이언트 등)
  - name: client
    instanceType: t3.medium
    minSize: 1
    maxSize: 1
    desiredCapacity: 1
    privateNetworking: true
    availabilityZones: ["ap-northeast-2a"]
    labels:
      role: client

현재 사용중인 profile을 확인하고

aws sts get-caller-identity --profile kyeongjun-dev

ekstctl로 설치를 진행한다.

eksctl create cluster -f cluster.yaml --profile kyeongjun-dev

load balancer controller 사용하기

aws load balancer controller 설치 (링크)

policy를 다운로드 받는다. (10/iam_policy.json)

curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.13.3/docs/install/iam_policy.json

iam policy를 생성한다.

aws --profile kyeongjun-dev iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json

클러스터 생성이 완료되면, kubeconfig를 가져온다.

aws eks update-kubeconfig --region ap-northeast-2 --name my-cluster --profile kyeongjun-dev

eksctl로 oidc가 연동된 iam role을 생성한다.

eksctl create iamserviceaccount \
    --cluster=my-cluster \
    --namespace=kube-system \
    --name=aws-load-balancer-controller \
    --attach-policy-arn=arn:aws:iam::<AWS 계정 ID>:policy/AWSLoadBalancerControllerIAMPolicy \
    --override-existing-serviceaccounts \
    --region ap-northeast-2 \
    --approve \
    --profile kyeongjun-dev

kube-system에 설치된 service account를 확인한다.

kubectl get sa -n kube-system aws-load-balancer-controller                                 
NAME                           SECRETS   AGE
aws-load-balancer-controller   0         92s

helm repo를 추가하고

helm repo add eks https://aws.github.io/eks-charts
helm repo update eks

helm 차트 수정을 위해 pull 진행

helm pull eks/aws-load-balancer-controller
tar xf aws-load-balancer-controller-1.16.0.tgz
rm aws-load-balancer-controller-1.16.0.tgz

원본 유지를 위해 values 파일 복사

cp aws-load-balancer-controller/values.yaml albc-value.yaml

아래 내용대로 수정

diff albc-value.yaml aws-load-balancer-controller/values.yaml
5c5
< replicaCount: 1
---
> replicaCount: 2
32c32
<   create: false
---
>   create: true
37c37
<   name: aws-load-balancer-controller
---
>   name:
78,79c78
< nodeSelector:
<   role: infra
---
> nodeSelector: {}
136c135
< clusterName: my-cluster
---
> clusterName:

수정한 albc-value.yaml로 설치

helm install aws-load-balancer-controller eks/aws-load-balancer-controller -f albc-value.yaml -n kube-system

설치 확인

kubectl get pod -n kube-system aws-load-balancer-controller-667f7744d6-m76vg 
NAME                                            READY   STATUS    RESTARTS   AGE
aws-load-balancer-controller-667f7744d6-m76vg   1/1     Running   0          39s

add-on 파드 정리하기

infra 노드로 옮기기

현재 infra, client, server 노드그룹이 있는데 add-on 파드들이 정리되지 않고 모든 노드에 있다.

• client 노드

  kubectl get node -l role=client
  kubectl describe node ip-192-168-78-153.ap-northeast-2.compute.internal
  

Non-terminated Pods: (6 in total) Namespace Name CPU Requests CPU Limits Memory Requests Memory Limits Age

kube-system aws-node-xbpgz 50m (2%) 0 (0%) 0 (0%) 0 (0%) 9m18s kube-system coredns-c844dd74d-dhgnw 100m (5%) 0 (0%) 70Mi (2%) 170Mi (5%) 13m kube-system coredns-c844dd74d-z222h 100m (5%) 0 (0%) 70Mi (2%) 170Mi (5%) 13m kube-system kube-proxy-bltk7 100m (5%) 0 (0%) 0 (0%) 0 (0%) 9m18s kube-system metrics-server-7645d75fbf-2slfp 100m (5%) 0 (0%) 200Mi (6%) 400Mi (12%) 13m kube-system metrics-server-7645d75fbf-gkznr 100m (5%) 0 (0%) 200Mi (6%) 400Mi (12%) 13m

- server 노드

kubectl get node -l role=server kubectl describe node ip-192-168-89-251.ap-northeast-2.compute.internal

Non-terminated Pods: (2 in total) Namespace Name CPU Requests CPU Limits Memory Requests Memory Limits Age

kube-system aws-node-58j4k 50m (2%) 0 (0%) 0 (0%) 0 (0%) 10m kube-system kube-proxy-zgkbn 100m (5%) 0 (0%) 0 (0%) 0 (0%) 10m

core dns, metrics server를 infra 노드로 옮겨주자
- core dns

kubectl -n kube-system edit dep loyments.apps coredns

(변경 전) spec: affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/os operator: In values: - linux - key: kubernetes.io/arch operator: In values: - amd64 - arm64

(변경 후) spec: affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/os operator: In values: - linux - key: kubernetes.io/arch operator: In values: - amd64 - arm64 - key: role operator: In values: - infra

- metrics server

kubectl -n kube-system edit deployments.apps metrics-server

(변경 전) spec: affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/os operator: In values: - linux - key: kubernetes.io/arch operator: In values: - amd64 - arm64

(변경 후) spec: affinity: nodeAffinity: requiredDuringSchedulingIgnoredDuringExecution: nodeSelectorTerms: - matchExpressions: - key: kubernetes.io/os operator: In values: - linux - key: kubernetes.io/arch operator: In values: - amd64 - arm64 - key: role operator: In values: - infra

개수도 2개는 필요 없으니 줄여주자

kubectl -n kube-system scale deployment coredns --replicas 1 kubectl -n kube-system scale deployment metrics-server --replicas 1

# NLB 만들고 어플리케이션 연결하기
### client, server 배포
namspace 생성

kubectl create ns client kubectl create ns server

`10/client.yaml`, `10/server.yaml` 생성

kubectl apply -f client.yaml -n client kubectl apply -f server.yaml -n server

### target group 및 target gorup binding 만들기
먼저 아래 스크린샷을 참고하여 target group을 생성한다.
![](https://velog.velcdn.com/images/kyeongjun-dev/post/d1aaa4b9-8e90-4e33-b41b-5f85aa959877/image.png)




생성한 target group의 arn을 입력해서 target group binding을 생성한다. (`10/tgb.yaml`)

apiVersion: elbv2.k8s.aws/v1beta1 kind: TargetGroupBinding metadata: name: server spec: serviceRef: name: server port: 8000 targetGroupARN:

등록이 됐는지 확인한다.
![](https://velog.velcdn.com/images/kyeongjun-dev/post/0bbd0389-d651-420a-be26-93781f6104aa/image.png)


### NLB 만들기
콘솔에서 network 타입으로 생성을 시작한다. internal로 지정해준다.

![](https://velog.velcdn.com/images/kyeongjun-dev/post/ad23bd7e-5659-4519-999c-268dfb420f3e/image.png)

네트워크 설정은 eksctl로 클러스터를 생성할 때, 자동으로 생성된 vpc랑 subnet을 사용한다. az는 2a만 지정했고, subnet이 총 2개(Public, Private)있는데, public을 선택하면 경고 메시지가 발생한다. (두 번째 스크린샷 참고)
![](https://velog.velcdn.com/images/kyeongjun-dev/post/4bb6300d-e7ff-42e8-a4bb-afad79f219a8/image.png)

![](https://velog.velcdn.com/images/kyeongjun-dev/post/db01acce-4310-4b7a-84b5-a4a80482fa58/image.png)


sg도 eksctl로 생성할 때 생성된 sg 중 `eks-cluster-sg`로 시작하는 걸 지정해준다. eks에 생성된 노드들에서 사용하는 sg다.
![](https://velog.velcdn.com/images/kyeongjun-dev/post/f566732e-c62a-49fc-a531-e0c77ebfe650/image.png)


리스너는 80포트, 타겟 그룹은 위에서 생성했던 타겟 그룹을 지정해서 생성을 마무리 한다. (나머지 값은 전부 기본 값)
![](https://velog.velcdn.com/images/kyeongjun-dev/post/8dabdeef-7538-45bb-afb8-5e172f7f28a0/image.png)

Active 상태가 되는 걸 확인한다.
![](https://velog.velcdn.com/images/kyeongjun-dev/post/0ff2f84e-504b-4473-bb78-1dfabc40d8c0/image.png)


### client에서 테스트
nlb의 `DNS name`으로 client.yaml을 수정해서 다시 apply 한다.(`10/client-nlb.yaml`)

apiVersion: v1 kind: Service metadata: name: client labels: app: client spec: ports: - port: 80 targetPort: 80 selector: app: client type: ClusterIP

apiVersion: apps/v1 kind: Deployment metadata: name: client labels: app: client spec: replicas: 1 selector: matchLabels: app: client template: metadata: labels: app: client spec: containers: - name: client image: ghcr.io/kyeongjun-dev/network:dev imagePullPolicy: Always command: ["sleep", "infinity"] env: - name: HOST value: "server-2f43e9b6339f7f95.elb.ap-northeast-2.amazonaws.com" - name: PORT value: "80" - name: HOST_HEADER value: "server-2f43e9b6339f7f95.elb.ap-northeast-2.amazonaws.com" - name: USE_TLS value: "false" - name: ENDPOINT value: "/" # value: "/slow?wait=11" nodeSelector: role: client

파드 이름을 확인하고, 요청을 보내본다.

kubectl get pod -n client NAME READY STATUS RESTARTS AGE client-64cfc6c5b5-vm6vl 1/1 Running 0 52s

kubectl -n client exec -it client-64cfc6c5b5-vm6vl -- python client.py 5

요청이 잘 되는 것을 확인한다.
![](https://velog.velcdn.com/images/kyeongjun-dev/post/5d07fae0-1305-4791-9229-8fd14ffc2a9c/image.png)

# 패킷 수집 해보기
### 명령어
`11/cmd` 파일을 참고해서, 케이스마다 파드 이름을 알아내고 입력하는 과정을 간소화해보자. 그리고 nlb의 외부 포트가 80이라 tcpdump 조건에 80과 8000을 지정했다.
deployment 재시작은 pod의 `.pcap` 파일을 없애주기 위해 진행한다.(tcpdump가 원래 파일을 덮어쓰는 지를 모르겠다.)

export CLIENT=$(kubectl get pod -n client | grep client | awk '{print $1}') export SERVER=$(kubectl get pod -n server | grep server | awk '{print $1}')

kubectl -n client exec -it $CLIENT -- tcpdump -i any -n 'port 80 or port 8000' -w /app/client.pcap kubectl -n server exec -it $SERVER -- tcpdump -i any -n 'port 80 or port 8000' -w /app/server.pcap

kubectl -n client exec -it $CLIENT -- python client.py 25 kubectl -n server logs -f $SERVER

kubectl -n client cp $CLIENT:/app/client.pcap client.pcap kubectl -n server cp $SERVER:/app/server.pcap server.pcap

kubectl -n client rollout restart deployment client kubectl -n server rollout restart deployment server

```

client interval 25, server keep-alive 20

먼저 client에서는 25초 후에 에러가 발생하는 것을 확인할 수 있다.

client 패킷을 확인해보자. client 192.168.91.27, server 192.168.72.184

server 패킷을 확인해보자.

패킷을 확인해보면, client 입장에서는 destination이 NLB이고 server 입장에서는 client가 NLB이기 때문에 nlb 192.168.79.34인 것을 확인할 수 있다.

• 0초 : 연결 및 GET 요청 전송
• 20초 : server가 nlb에 FIN 전송 및 연결 해제 완료
• 25초 : client가 없어진 연결로 GET 요청 전송 후, server에서 RST 전송

client interval 355, server keep-alive 360

kubectl edit으로 server Deployment의 --keep-alive 값을 360초로 변경한 뒤 테스트를 진행해보자. 원래 상황이라면 클라이언트의 요청 간격이 355초이고 서버의 keep alive가 360으로 더 길어서 문제가 없을 것이다.

요청을 보낸 직후 시간 기록을 위해 스크린샷

대략 400초가 지났을 때, 패킷을 확인해본다.

client, server 패킷은 아래와 같다. client 192.168.68.217, server 192.168.81.43, nlb 192.168.79.34

이전까지는 client, server 패킷이 근소한 시간차이를 두고 거의 동일했는데 nlb가 중간에 끼면서 달라진 것을 확인할 수 있다.

client 패킷을 먼저 분석하면

• 0초 : 연결 수립 및 GET 요청 전송
• 355초 : interval이 지나서 다시 GET 요청을 전송, nlb가 RST 패킷을 client에게 전송

server 패킷을 분석하면

• 0초 : nlb로 부터 연결 수립 및 GET 요청 수신
• 360초: keep alive 360초가 지날 때까지 아무런 작업이 없어서 FIN 패킷을 전송했으나, nlb로부터 RST 패킷 수신

이러한 현상이 발생하는 이유는, nlb의 기본 idle timeout이 350초이기 때문이다. 인터넷에 검색하면 아래 내용을 쉽게 찾을 수 있다.

nlb는 idle timeout (default: 350초)가 지나면, 연결 정보를 삭제한다. 삭제할 때는 client에 삭제했다는 사실을 알리지 않고 조용히 삭제한다.

결론 및 다음 글에서는

NLB를 사용할 경우, 백엔드 서버의 keep alive 시간을 350초 보다 작게 설정해야 함을 패킷 분석을 통해 알아봤다. 글을 작성하는 시기 기준으로, NLB의 idle timeout도 변경이 가능하지만(링크), tls 포트에 대해서는 설정이 불가능해서 350초가 고정이다.

다음 글에서는 ALB로 동일하게 테스트를 진행해보려고 한다.

원래 'AWS 환경에서 많이 사용되는 NLB, ALB를 사이에 두고 테스트랑 패킷 분석'을 해야하지만, 백엔드 서버에서 timeout 설정도 확실히 해두면 좋을 것 같아서 timeout일 때도 패킷 분석을 해보려고 한다.

백엔드 서버에 timeout 적용

소스코드 작성

일단 아래 이미지를 사용하면 된다.

docker pull ghcr.io/kyeongjun-dev/network:dev

app/app.py에 /에 추가로 /slow 엔드포인트를 추가했다. 실제 호출할 때는 /slow?wait=5 이런 식으로 wait 매개변수를 전달한다.

from flask import Flask, request
import time

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello from Flask App behind Gunicorn!"

@app.route('/slow')
def slow():
    try:
        wait_time = request.args.get('wait', default=10, type=int)
    except ValueError:
        # 쿼리 파라미터가 정수가 아닌 경우 10초를 사용합니다.
        wait_time = 10

    print(f"Request received. Busy waiting for {wait_time} seconds...")
    # CPU를 계속 사용하는 반복문 사용
    end_time = time.time() + wait_time
    while time.time() < end_time:
        pass  # 아무것도 안 하지만 CPU는 계속 씀 (Yield 안 함)

    print(f"Waited {wait_time} seconds. Sending response now.")
    return f"Finally, here is your slow response..."

timeout이 나는 원리

gunicorn을 아래와 같이 실행할 때, --timeout을 설정한다.

gunicorn --workers 1 -k gevent --bind 0.0.0.0:8000 --timeout 10 --keep-alive 10 app:app --log-level debug

이때 /slow?wait=초로 전달하는 초가 --timeout에 설정한 초보다 크면, 백엔드 서버에서 woker timeout이 발생한다.

실제로 실행시킨 후, curl로 11초를 지정해서 호출하면 WORKER TIMEOUT을 확인할 수 있다.

timeout 패킷 캡처해보기

docker compose로 테스트하기 (소스코드 : 레포 08 디렉토리)

아래 docker-compose를 08 디렉토리에서 실행한다.

services:
  server:
    image: ghcr.io/kyeongjun-dev/network:dev
    hostname: server
    container_name: server
    volumes:
      - ./server_vol:/app/captures
    ports:
      - "8000:8000"
    command: ["gunicorn", "--workers", "1", "-k", "gevent", "--bind", "0.0.0.0:8000", "--timeout", "10", "--keep-alive", "10", "app:app", "--log-level", "debug"]

  client:
    image: ghcr.io/kyeongjun-dev/network:dev
    container_name: client
    volumes:
      - ./client_vol:/app/captures
    command: ["sleep", "infinity"]
    environment:
      HOST: server
      PORT: 8000
      HOST_HEADER: server
      USE_TLS: false
      ENDPOINT: /slow?wait=11

이제 빌드해둔 이미지가 있으므로, ghcr에 올려놓은 이미지를 사용한다. (-d는 백그라운드 실행)

docker-compose up -d

tcpdump를 실행하고

docker exec -it client tcpdump -i any -n 'port 8000' -w /app/captures/client.pcap
docker exec -it server tcpdump -i any -n 'port 8000' -w /app/captures/server.pcap

client에서 server로 요청을 전송한다

docker exec -it client python client.py 11

server 로그를 확인해보면, 08:00:54에 GET 요청을 받은 후, 약 10초 뒤인 08:01:05에 WORKER TIMEOUT이 발생했다.

패킷 분석하기

client가 172.19.0.3, server가 172.19.0.2

간단히 분석해보면

1. 0초 : tcp 연결 완료
2. 0초대에 /slow?wait=11로 GET 요청 전송
3. (패킷에 안보임) 10초 대에 WORKER TIMEOUT으로 워커 종료
4. 20초 : --keep-alive 10 설정에 의해 10초 뒤인 20초대에 client에 FIN 전송

client(172.19.0.3), server(172.19.0.2)--keep-alive를 20초로 변경한 후, 테스트 했을 때의 패킷은 아래와 같다. 즉, FIN 패킷을 전송할 때까지 걸리는 시간은 timeout + keep alive 타임이다.

위를 보면, 워커가 작업을 수행하는 시간은 keep alive에 포함되지 않는 것 같다.

정리 및 다음 글에서는...

timeout까지 고려하려니 너무 복잡해지는 거 같다. 다음 글 부터는 /slow를 이용해 timeout은 후순위로 고려하려고 한다. 다음 글에서는 AWS 환경 EKS에 nlb를 두고, 패킷 테스트를 해보자. (이제 진짜 돈이 들겠네...)

https://github.com/kyeongjun-dev/network

개요

실제 백엔드 서비스에서 테스트해보기

시리즈3에서는 파이썬으로 만든 client, server 스크립트 파일로 테스트를 진행하고 tcpdump를 이용해 패킷을 분석했다. 이번 글에서는 실제 백엔드 서버를 server 역할로 두고 테스트를 진행해본다. 사용하는 백엔드는 gunicorn과 flask다.

백엔드 서버 만들기

gunicorn, flask 코드 작성 (소스코드 : 레포 06/flask 디렉토리)

먼저 flask 코드(06/flask/app.py)다. 정말 간단하게 /로 접근 시, 문자열을 return (status : 200) 한다.

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello from Flask App behind Gunicorn!"

설치하는 파이썬 패키지는 아래와 같다. (06/flask/requirements.txt)

Flask==3.1.2
gunicorn==23.0.0
gevent==25.9.1

패키지 별로 간단히 설명을 붙이자면 아래와 같다.

• flask : API 서버 역할을 수행.
• gunicorn : WSGI로, flask 앞단에서 client와의 연결 수행.
• gevent : gunicorn의 기본 워커는 동기(sync)인데, gevent를 워커타입으로 설정하여 비동기(async)로 사용 - gunicorn의 경우 워커가 비동기여야keep alive 설정이 적용됨 (공식문서링크)

다음은 실행 명령어다. (06/flask/cmd)

gunicorn --workers 1 -k gevent --bind 0.0.0.0:8000 --timeout 10 --keep-alive 10 app:app --log-level debug

실행 명령어 설명은 아래와 같다. 자세한 설명은 공식문서링크 참고 가능

• --workers : gunicorn을 실행할 때, 워커 개수를 지정한다.
• -k(--worker-class) : 실행하는 워커 타입을 지정한다. 기본값은 sync
• --bind : 주소랑 포트를 지정해서 실행
• --timeout : 워커가 동작을 처리하는 최대 시간을 지정. 이 시간을 초과하도록 작업을 끝내지 못하면, 작업을 진행중인 워커 프로세스는 종료된다.
• --keep-alive : client랑 Keep-Alive 연결을 지속하는 시간을 지정. 이 시간을 초과하도록 아무런 작업(패킷교환)이 없으면, 연결을 종료한다.
• --log-level : gunicorn의 로그레벨을 설정. debug로 설정하고 gunicorn을 실행하면, 현재 설정된 값들을 확인할 수 있다.

클라이언트 만들기

파이썬으로 스크립트 작성

06/client.py 파일로, 실행할 때 요청을 보내는 time interval을 매개변수로 입력한다. 입력하지 않으면, 기본 값으로 60초 간격으로 요청을 보낸다.

import socket
import time
import errno
import sys  # 1. sys 모듈 임포트

# --- TIME_INTERVAL 설정 로직 ---
TIME_INTERVAL = 60  # 2. 기본값 60초

try:
    if len(sys.argv) > 1:
        # 3. 커맨드라인 인자(argv[1])가 있으면, 그것을 TIME_INTERVAL로 사용
        TIME_INTERVAL = int(sys.argv[1])
    else:
        # 4. 커맨드라인 인자가 없으면, 사용자에게 입력받음
        user_input = input('insert TIME_INTERVAL (default 60): ')

        if user_input:
            # 5. 사용자가 값을 입력한 경우
            TIME_INTERVAL = int(user_input)
        # (사용자가 아무것도 입력하지 않으면(Enter), 기본값 60이 사용됨)

except ValueError:
    print(f"Error: Invalid input. Using default TIME_INTERVAL = 60s.")
    TIME_INTERVAL = 60
except KeyboardInterrupt:
    print("\nCanceled by user. Exiting.")
    sys.exit(0)
# ------------------------------


# --- 설정 ---
HOST = 'localhost'
PORT = 8000
YOUR_HOST_HEADER = 'localhost'
# -----------

# 사용할 요청 (GET /)
REQUEST_KEEP_ALIVE = (
    f"GET / HTTP/1.1\r\n"
    f"Host: {YOUR_HOST_HEADER}\r\n"
    # keep alive 연결 명시
    f"Connection: keep-alive\r\n"
    f"\r\n"
).encode('utf-8')


print(f"\n--- Keep-Alive Test (Non-TLS) ---")
# 6. http:// 스키마 및 포트 번호 명시
print(f"Target: http://{HOST}:{PORT}") 
print(f"Sending 'GET /' request every {TIME_INTERVAL} seconds.")
print("Press Ctrl+C to stop the test.")

s = None # finally 블록에서 s를 참조할 수 있도록 외부에 선언
try:
    # 1. 소켓 생성 연결 (Non-TLS)
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    print(f"\nConnecting to {HOST}:{PORT} (TCP)...")
    s.connect((HOST, PORT))
    print("TCP Connected!")

    # 2. 첫 번째 요청 전송 (연결 확인용)
    print("\n--- Sending first request (GET /) ---")
    s.sendall(REQUEST_KEEP_ALIVE)

    # 3. 첫 번째 응답 수신
    response = s.recv(4096)
    if not response:
        print("\n*** TEST FAILED: Received empty response on first request. ***")
        raise socket.error("Server returned empty response on first request")

    print("--- Received first response ---")
    print(response.decode('utf-8', errors='ignore').split('\r\n')[0])

    # 4. TIME_INTERVAL 간격으로 요청 무한 반복
    count = 1
    while True:
        print(f"\n--- Waiting for {TIME_INTERVAL} seconds... ---")
        time.sleep(TIME_INTERVAL)

        count += 1
        print(f"--- Sending keep-alive request #{count} (GET /) ---")
        s.sendall(REQUEST_KEEP_ALIVE)

        # 응답 수신
        response = s.recv(4096)

        # 서버가 연결을 닫았는지 확인 (0바이트 수신)
        if not response:
            print("\n*** TEST FAILED: Server closed connection (recv() returned 0 bytes) ***")
            raise socket.error(errno.ECONNRESET, "Connection closed by peer (recv() returned 0)")

        print(f"--- Received response #{count} ---")
        print(response.decode('utf-8', errors='ignore').split('\r\n')[0])


except socket.error as e:
    # 5. 연결이 끊어지면 "실패"로 간주 (Keep-Alive 실패)
    if e.errno in (errno.ECONNRESET, errno.EPIPE):
        print(f"\n*** TEST FAILED: Connection was reset by peer! ***")
        print(f"Error (Code: {e.errno}): {e.strerror}")
    else:
        print(f"\n*** TEST FAILED: Caught unexpected socket error ***")
        print(f"Error (Code: {e.errno}): {e.strerror}")
except KeyboardInterrupt:
    # 6. 사용자가 Ctrl+C로 정상 종료
    # (루프가 시작되기 전에 중단될 경우 'count' 변수가 없을 수 있어 'locals()'로 확인)
    req_count_str = f" after {count} requests" if 'count' in locals() else ""
    print(f"\n\n--- Test manually interrupted by user (Ctrl+C){req_count_str}. ---")
    print("*** TEST STOPPED ***")
except Exception as e:
    print(f"\n*** TEST FAILED: Caught a non-socket error ***")
    print(f"Error: {e}")

finally:
    if s:
        s.close()
        print("\nSocket closed.")

ping-pong 테스트하기

로컬에서 테스트하기 (소스코드 : 레포 06 디렉토리)

먼저 백엔드 서버를 실행한다.

// 06/flask 디렉토리로 이동
cd 06/flask

// venv 생성
python3.13 -m venv venv

// venv 활성화
source venv/bin/activate

// 파이썬 패키지 설치
pip install -r requirements.txt

// gunicorn 백엔드 서버 실행
gunicorn --workers 1 -k gevent --bind 0.0.0.0:8000 --timeout 10 --keep-alive 10 app:app --log-level debug

다음으로 06/client.py를 8초로 실행한다.

python3.13 client.py 8

8초 간격으로 GET 요청이 잘 전달되는 것을 확인할 수 있다.

다음으로 06/client.py를 11초롤 실행한다.

python3.13 client.py 11

8초로 실행했을 때와 달리 2번째 요청부터 바로 실패하는 것을 확인할 수 있다.

docker compose로 패킷 확인해보기 (소스코드 : 레포 07 디렉토리)

07/client/client.py를 8초, 15초(11초로 했을 시, 요청이 성공하는 케이스가 존재함)로 실행했을 때의 패킷을 tcpdump랑 wireshark로 확인해보자.

import socket
import time
import errno
import sys  # 1. sys 모듈 임포트

# --- TIME_INTERVAL 설정 로직 ---
TIME_INTERVAL = 60  # 2. 기본값 60초

try:
    if len(sys.argv) > 1:
        # 3. 커맨드라인 인자(argv[1])가 있으면, 그것을 TIME_INTERVAL로 사용
        TIME_INTERVAL = int(sys.argv[1])
    else:
        # 4. 커맨드라인 인자가 없으면, 사용자에게 입력받음
        user_input = input('insert TIME_INTERVAL (default 60): ')

        if user_input:
            # 5. 사용자가 값을 입력한 경우
            TIME_INTERVAL = int(user_input)
        # (사용자가 아무것도 입력하지 않으면(Enter), 기본값 60이 사용됨)

except ValueError:
    print(f"Error: Invalid input. Using default TIME_INTERVAL = 60s.")
    TIME_INTERVAL = 60
except KeyboardInterrupt:
    print("\nCanceled by user. Exiting.")
    sys.exit(0)
# ------------------------------


# --- 설정 ---
HOST = 'server'
PORT = 8000
YOUR_HOST_HEADER = 'server'
# -----------

# 사용할 요청 (GET /)
REQUEST_KEEP_ALIVE = (
    f"GET / HTTP/1.1\r\n"
    f"Host: {YOUR_HOST_HEADER}\r\n"
    # keep alive 연결 명시
    f"Connection: keep-alive\r\n"
    f"\r\n"
).encode('utf-8')


print(f"\n--- Keep-Alive Test (Non-TLS) ---")
# 6. http:// 스키마 및 포트 번호 명시
print(f"Target: http://{HOST}:{PORT}") 
print(f"Sending 'GET /' request every {TIME_INTERVAL} seconds.")
print("Press Ctrl+C to stop the test.")

s = None # finally 블록에서 s를 참조할 수 있도록 외부에 선언
try:
    # 1. 소켓 생성 연결 (Non-TLS)
    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    print(f"\nConnecting to {HOST}:{PORT} (TCP)...")
    s.connect((HOST, PORT))
    print("TCP Connected!")

    # 2. 첫 번째 요청 전송 (연결 확인용)
    print("\n--- Sending first request (GET /) ---")
    s.sendall(REQUEST_KEEP_ALIVE)

    # 3. 첫 번째 응답 수신
    response = s.recv(4096)
    if not response:
        print("\n*** TEST FAILED: Received empty response on first request. ***")
        raise socket.error("Server returned empty response on first request")

    print("--- Received first response ---")
    print(response.decode('utf-8', errors='ignore').split('\r\n')[0])

    # 4. TIME_INTERVAL 간격으로 요청 무한 반복
    count = 1
    while True:
        print(f"\n--- Waiting for {TIME_INTERVAL} seconds... ---")
        time.sleep(TIME_INTERVAL)

        count += 1
        print(f"--- Sending keep-alive request #{count} (GET /) ---")
        s.sendall(REQUEST_KEEP_ALIVE)

        # 응답 수신
        response = s.recv(4096)

        # 서버가 연결을 닫았는지 확인 (0바이트 수신)
        if not response:
            print("\n*** TEST FAILED: Server closed connection (recv() returned 0 bytes) ***")
            raise socket.error(errno.ECONNRESET, "Connection closed by peer (recv() returned 0)")

        print(f"--- Received response #{count} ---")
        print(response.decode('utf-8', errors='ignore').split('\r\n')[0])


except socket.error as e:
    # 5. 연결이 끊어지면 "실패"로 간주 (Keep-Alive 실패)
    if e.errno in (errno.ECONNRESET, errno.EPIPE):
        print(f"\n*** TEST FAILED: Connection was reset by peer! ***")
        print(f"Error (Code: {e.errno}): {e.strerror}")
    else:
        print(f"\n*** TEST FAILED: Caught unexpected socket error ***")
        print(f"Error (Code: {e.errno}): {e.strerror}")
except KeyboardInterrupt:
    # 6. 사용자가 Ctrl+C로 정상 종료
    # (루프가 시작되기 전에 중단될 경우 'count' 변수가 없을 수 있어 'locals()'로 확인)
    req_count_str = f" after {count} requests" if 'count' in locals() else ""
    print(f"\n\n--- Test manually interrupted by user (Ctrl+C){req_count_str}. ---")
    print("*** TEST STOPPED ***")
except Exception as e:
    print(f"\n*** TEST FAILED: Caught a non-socket error ***")
    print(f"Error: {e}")

finally:
    if s:
        try:
            # 소켓을 닫기 전에 남은 데이터를 싹 비웁니다.
            s.settimeout(0.1) # 타임아웃을 짧게 설정
            while True:
                data = s.recv(4096)
                if not data: break
        except Exception:
            pass # 타임아웃이나 에러가 나면 그냥 무시

        s.close() # 이제 버퍼가 비었으므로 FIN을 보냄
        print("\nSocket closed.")

8초 간격으로 요청 보내기

먼저 docker-compose로 client, server 컨테이너를 실행한다.

docker-compose up --build

client, server 컨테이너에 각각 tcpdump를 실행한다. - 8000번 포트로 변경됐다.

docker exec -it client tcpdump -i any -n 'port 8000' -w /app/captures/client.pcap
docker exec -it server tcpdump -i any -n 'port 8000' -w /app/captures/server.pcap

먼저 client.py를 8초로 실핸한다.

docker exec -it client python client.py 8

5회만 요청을 확인한 뒤, Ctrl + C로 client를 종료한다.

tcpdump를 실행한 터미널에서도 Ctrl + C로 종료한 뒤, client_vol, server_vol에 생성된 .pcap 파일을 확인한다.

8초로 실행했을 때의 패킷을 wireshark로 확인한다.

패킷 분석은 간단하게, 5번 요청을 보내고 36초에 client(172.22.0.2)에서 server(172.22.0.3)에 FIN 패킷을 전송하고 연결이 끝난다.

15초 간격으로 요청 보내기

docker compose down으로 종료한 뒤, client_vol, server_vol 디렉토리를 삭제한 뒤 동일하게 docker compose up과 tcpdump까지 실행한다.

docker-compose down -v
rm -rf client_vol server_vol

docker-compose up --build
docker exec -it client tcpdump -i any -n 'port 8000' -w /app/captures/client.pcap
docker exec -it server tcpdump -i any -n 'port 8000' -w /app/captures/server.pcap
docker exec -it client python client.py 15

15초 후의 요청이 바로 실패하는 것을 확인할 수 있다.

tcpdump한 파일을 wireshark로 확인해보면 아래와 같다.

client.pcap 기준, 시간대별로 해석해보면 아래와 같다. client(172.22.0.2), server(172.22.0.3)

• 0 ~ 0.000026 : tcp 연결
• 0.000071 ~ 0.000075 : 열결 확인용 첫 번째 GET 요청 전송
• 0.001427 ~ 0.001456 : 첫 번째 응답 수신
• 10.004 : server에서 client에 FIN 패킷 전달
• 10.045 : client에서 server에 ACK 패킷 전달 >> tcp 연결 종료 - gunicorn의 keep-alive 10초 설정의 효과
• 15.004438 : client가 연결이 닫힌 줄 모르고, GET 요청을 server에 전달
• 15.004490 : server가 client에게 RST 패킷을 전달해서, 이미 닫힌 연결임을 알림

정리 및 다음 글에서는...

이번 글에서는 실제 백엔드 서버 중 하나인 gunicorn에서 keep-alive가 어떻게 동작하는지 확인했다. 하나 확인할 수 있는 것은 아래와 같다.

client에서는 server의 keep-alive 설정 시간 내에 작업을 끝내고, 연결을 명시적으로 끊어줘야 한다. keep-alive 연결을 계속 이용하려면, client에서 server에 '이 연결은 유효한 연결이에요'를 server의 keep-alive 시간 내에 계속 알려줘야 한다.

지금까지는 로컬에서 docker compose를 이용해 client, server 컨테이너 2개만 이용하여 테스트를 진행했다. 하지만 실제 환경에서 위처럼 사용하는 경우는 없다. 대부분의 경우, 아래와 같이 중간에 load balancer가 쓰이기 때문이다.

1. client > load balancer > server
2. client > load balancer > proxy server > server

이제 AWS 환경에서 많이 사용되는 NLB, ALB를 사이에 두고 테스트랑 패킷 분석을 해보자.

https://github.com/kyeongjun-dev/network

개요

소켓의 timeout은 어떻게 동작할까?

시리즈 2에서 server 코드에 server_socket.settimeout(10)을 설정하여 10초동안 client에서 연결하지 않으면, server가 종료된다고 언급했다. 그런데 사실 10초동안 '연결'이 안되면 종료하는 것에 더하여, 연결된 후로 '10초 동안 아무런 동작을 하지 않으면' 조건에서도 종료된다.

정리하자면

1. 소켓의 timeout은 10초동안 client로부터 연결이 없으면, 종료된다.
2. 소켓의 timeout은 연결된 후, 10초동안 아무런 활동이 없으면 종료된다.

이를 실제로 구현하고 테스트해보자.

실제로 해보기

client에서 시간차로 메시지 전송(ping-pong) 해보기 - (소스코드 : 레포 04 디렉토리)

timeout(여기선 10초)로 설정된 소켓을 생성한 뒤, client로부터 전송된 메시지를 출력한다. - 04/server.py 파일

import socket

timeout_duration = 10

server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server_socket.bind(('127.0.0.1', 30000))
server_socket.listen()
print("클라이언트 접속을 기다립니다...")

# accept()는 블로킹 상태로 무한정 대기
client_socket, addr = server_socket.accept()
print(f"{addr} 에서 접속했습니다. 이제부터 {timeout_duration}초 내에 데이터를 보내야 합니다.")

# 'accept'로 생성된 클라이언트와의 통신 소켓에 타임아웃(timeout_duration) 설정
client_socket.settimeout(timeout_duration)

while True:
    try:
        # recv()는 데이터가 들어올 때까지 여기서 실행을 멈춤(blocking)
        # settimeout() 때문에 timeout_duration초가 지나면 socket.timeout 예외를 발생시킴
        data = client_socket.recv(1024)

        # 클라이언트가 연결을 정상적으로 종료한 경우
        if not data:
            print("클라이언트가 연결을 끊었습니다.")
            break

        print(f"수신 메시지: {data.decode('utf-8')}")
        client_socket.sendall("메시지를 잘 받았습니다!".encode('utf-8'))

    except socket.timeout:
        print(f"{timeout_duration}초 동안 데이터 수신이 없어 연결을 종료합니다.")
        break # while 루프 탈출

    except ConnectionResetError:
        print("클라이언트와의 연결이 비정상적으로 끊어졌습니다.")
        break

    except Exception as e:
        print(f"오류가 발생했습니다: {e}")
        break

# 소켓 정리
print(f"{addr} 와의 연결을 닫습니다.")
client_socket.close()
server_socket.close()

연결된 후, timeout_duration에 설정된 초만큼 아무것도 하지 않고 기다린다. 이때 이 값을 04/server.py의 timeout 시간보다 길게 한다(여기선 15초) - 04/client.py 파일이다.

import socket
import time

client_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

try:
    client_socket.connect(('127.0.0.1', 30000))
    print("서버에 접속했습니다.")
    print("아무 내용이나 입력 후 엔터를 누르면 서버로 메시지를 보냅니다.")
    print("10초 이상 아무것도 안 하면 서버에서 연결이 끊깁니다.")
    print("종료하려면 'exit'을 입력하세요.")

    while True:
        wait_start_time = time.time()
        # 사용자 입력 대기
        message = input("> ")
        print(f"{time.time() - wait_start_time}초 이후에 메시지를 전송합니다.")
        if message.lower() == 'exit':
            break

        # 메시지 전송
        client_socket.sendall(message.encode('utf-8'))

        # 서버로부터 응답 수신
        data = client_socket.recv(1024)
        print(f"서버 응답: {data.decode('utf-8')}")

except ConnectionRefusedError:
    print("서버에 연결할 수 없습니다.")
except (ConnectionResetError, BrokenPipeError):
    print("서버에 의해 연결이 끊겼습니다.")
except Exception as e:
    print(f"오류가 발생했습니다: {e}")

finally:
    print("클라이언트를 종료합니다.")
    client_socket.close()

04/server.py를 실행한 뒤, 04/client.py를 실행하고 server의 timeout 이내에 메시지를 전송하면 계속 ping-pong이 되다가 timeout이 넘어서 메시지를 전송하면 server는 종료되고, client도 연결을 종료한다.

위 캡처에서 10.75초 이후에 메시지를 전송했을 때, 빈 문자열이 서버 응답으로 오는데 이는 서버로부터 빈 문자열 b''를 받았기 때문이다. 이를 실제로 wireshark로 패킷 분석해보자. (소스코드 : 레포 05 디렉토리)

패킷 분석해보기

docker compose로 tcpdump (소스코드 : 레포 05 디렉토리)

05 디렉토리로 이동 후, docker compose를 실행한다.

docker-compose up --build

05/cmd파일을 참고해서 clinet, server 컨테이너에서 tcpdump를 진행한다.

docker exec -it client tcpdump -i any -n 'port 30000' -w /app/captures/client.pcap
docker exec -it server tcpdump -i any -n 'port 30000' -w /app/captures/server.pcap

05/cmd 파일을 참고해서 client, server 스크립트를 실행시킨 후 10초 내에 메시지 전송 및 10초 이후에 메시지 전송을 진행한다.

tcpdump를 Ctrl + C로 종료한다. 그리고 wireshark로 패킷을 확인한다.

분석을 해보면 (server가 172.22.0.2, client가 172.22.0.3)

1. ~0초 : tcp 연결
2. 3.6초 : client가 server에 hello 메시지 전송 및 server가 client에게 응답
3. 8.4초 : client가 server에 world 메시지 전송 및 server가 client에게 응답
4. 18.4초 : server가 client에 FIN, ACK 전송 및 client가 server에 ACK 응답 - tcp 연결 해제
5. 20.3초 : client가 server에 메시지를 전송하지만, 이미 닫힌 연결이라서 server가 client가 RST 전송 - tcp 연결은 해제되었지만, client 코드상에서는 사용자의 input을 그대로 기다림

정리 및 다음 글에서는...

05정도만 되도 어느정도 ping-pong하는 시나리오를 테스트할 수 있다. 하지만 결국 실제 백엔드 서버에서 어떻게 동작하는지 테스트를 하지 않으면 와닿지(?) 않기 때문에 다음 글에서는 gunicorn + flask 조합으로 백엔드 서버를 구성하고, 패킷 분석도 해보도록 한다.

https://github.com/kyeongjun-dev/network

개요

wireshark로 패킷 분석하기

쉬어가는 느낌으로 시리즈 1의 상황을 직접 패킷분석해보려고 한다. 먼저 wireshark가 설치되어 있어야 하고, tcpdump 명령어 사용이 가능해야 한다.

실제로 해보기

docker compose로 컨테이너 2개 실행

로컬에서 해도 되지만, 구분되는게 편할 거 같아서 docker compose로 컨테이너 2개를 띄운다. (소스코드 : 레포 03 디렉토리)

먼저 03 디렉토리로 이동한 뒤, 아래 명령어로 컨테이너 2개를 실행한다. 컨테이너는 네트워크 관련 패키지들이 설치된 파이썬 컨테이너다.

docker-compose up --build

아래와 같이 client, server 디렉토리가 생성된 것을 확인할 수 있다.

tcp dump 및 client에서 server 접속

이제 server 컨테이너로 접속해서 01-server.py를 실행시킨다.

docker exec -it server tcpdump -i any -n 'port 30000' -w /app/captures/server.pcap

client 컨테이너로도 접속해서 tcpdump를 실행한다.

docker exec -it client tcpdump -i any -n 'port 30000' -w /app/captures/client.pcap

터미널을 하나 더 열어서 server 컨테이너로 접속한 뒤, 01-server.py를 실행시킨다.

docker exec -it server python 01-server.py

터미널을 하나 더 열어서 client 컨테이너로 접속한 뒤, 01-client.py를 실행시킨다.

docker exec -it client python 01-client.py

01-client.py랑 01-server.py는 연결 주소를 127.0.0.1에서 server로 변경했다. (docker compose로 실행될 때 호스트네임이 각각 client, server로 변경된다.)

아래와 같이 정상 연결이 확인되면

tcpdump를 실행한 터미널에서는 Ctrl + C로 종료시켜준다.

wireshark로 패킷 확인

이제 컨테이너랑 마운트 된 경로에 아래처럼 파일 2개가 생성된 것을 확인할 수 있다.

client, server 패킷을 확인해보자. mac 기준으로 wireshark 창을 여러 개 띄우려면 open -n /Applications/Wireshark.app/로 여러 개를 띄운다.

172.22.0.2는 client, 172.22.0.3은 server다 - docker inspect server, docker inspect client 에서 ip 주소 확인이 가능하다.

분석해보자면

• TCP 3-Way Handshake(연결)

1. client > server : SYN 전송
2. server > client : SYN, ACK 전송
3. client > server : ACK 전송 - tcp 연결 완료

• 4-Way Handshake(종료)

4. client > server : FIN, ACK 전송 - tcp 종료 시작
5. server > client : FIN, ACK 전송
6. client > server : ACK 전송 - tcp 연결 종료

여러 케이스 별 패킷 분석

client가 1초 간격으로 시도하는 도중, server 실행

02-client.py를 실행하고, 약 5초 후에 02-server.py를 실행했다.

패킷은 아래와 같다. docker compose를 다시 실행했는데, 이번에는 client가 172.22.0.3이고, server가 172.22.0.2 이다.

분석해보자면

1. client가 server로 연결요청(SYN)을 보냄
2. 서버는 연결할 수 없다며 RST, ACK 패킷을 client에 전송함
3. client는 1초 단위로 연결을 재시도 하므로, 위 1~2 과정을 총 5번 반복
4. 약 5초 뒤 server가 실행되고, 정상적으로 연결을 맺음
5. 연결된 직후, client가 FIN, ACK를 전송해서 tcp 연결 종료

정리 및 다음 글에서는...

이런 식으로 wireshark를 이용해 패킷을 분석할 수 있다. 지금은 단순히 client, server만 로컬에 띄워서 테스트해서 패킷 분석이 간단하지만, 중간에 load balancer나 istio 같은 컴포넌트가 끼게되면 더욱 복잡해진다. 힘들지만 해보자...

https://github.com/kyeongjun-dev/network

개요

이 시리즈를 왜 쓰는가?

MSA 형태의 서비스들에서 best practice가 있다. client의 timeout과 server의 keep-alive 상태 등을 설정하는 좋은 예시들이 있다. 그러다가 문득 '그럼 어떤 상태에서 의도한 에러를 발생시킬 수 있을까?'라는 생각이 들었고, 이를 실천해보기 위해 이 시리즈를 작성하게 됐다. 주 목적은 미래의 내가 보기 위해서다.

시리즈 초반에는 실무에 도움이 될 수 있나 싶겠지만, 실제로 많은 도움이 됐고, 수많은 5xx에러를 없앴다.

소켓 연결 테스트 해보기

소켓 연결은 어떻게 되나?

server가 소켓을 열어두고, client가 서버로 접속한다. 실제 코드로 간단하게 테스트 해보자. (소스코드 : 레포 01 디렉토리)

먼저 client 코드다. 간단히 로컬호스트(127.0.0.1)의 30000 포트로 접속한다.

import socket

try:
    # AF_INET : ipv4 사용, SOCK_STREAM : tcp 사용
    client_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    client_socket.connect(('127.0.0.1', 30000))
    print("서버에 연결 시도...")
except ConnectionRefusedError:
    print("서버에 연결할 수 없습니다. 서버가 이미 종료된 것 같습니다.")
except Exception as e:
    print(f"오류가 발생했습니다: {e}")
finally:
    client_socket.close()

다음은 server 코드다. 간단히 30000번 포트로 소켓을 열고, client의 연결을 기다린다.

import socket

# 서버 소켓 생성
server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server_socket.bind(('127.0.0.1', 30000))
server_socket.listen()

try:
    # accept()는 클라이언트가 연결할 때까지 여기서 실행을 멈춤(blocking)
    client_socket, addr = server_socket.accept()
    print(f"{addr} 에서 접속했습니다.")

    # 연결 성공 후 로직 (여기서는 간단히 연결 종료)
    client_socket.close()
except Exception as e:
    print(f"오류가 발생했습니다: {e}")

finally:
    # 소켓 정리
    server_socket.close()
    print("서버 소켓을 닫았습니다.")

실제로 server.py, client.py 순서로 다른 터미널 창에서 실행해보면 아래와 같이 단순히 연결에 성공한 뒤, 바로 연결을 종료한다.

python3.13 client.py
서버에 연결 시도...

// 이걸 먼저 실행
python3.13 server.py
('127.0.0.1', 50460) 에서 접속했습니다.
서버 소켓을 닫았습니다.

문제점이 뭔가?

위의 01번 상황에서는 여러 문제가 있다.

1. server가 기약없이 계속 client를 기다린다.
2. client는 연결에 실패하면 바로 연결을 종료한다.

   // server.py를 실행하지 않고, 바로 client.py를 실행했을 때
   python3.13 client.py
   서버에 연결할 수 없습니다. 서버가 이미 종료된 것 같습니다.

이를 개선해보자.

타임아웃 설정하기

client와 server에 타임아웃을 설정해보자. (소스코드 : 레포 02 디렉토리)

먼저 server 코드다. timeout_duration에 설정한 10초만큼 대기한다.

import socket

server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
server_socket.bind(('127.0.0.1', 30000))
server_socket.listen()

timeout_duration = 10  # 총 대기 시간 (초)

try:
    # 서버 소켓이 클라이언트의 접속을 기다리는 시간을 timeout_duration으로 설정
    server_socket.settimeout(timeout_duration)

    client_socket, addr = server_socket.accept()
    print(f"{addr} 에서 접속했습니다.")

    client_socket.close()
except Exception as e:
    print(f"오류가 발생했습니다: {e}")

finally:
    server_socket.close()
    print("서버 소켓을 닫았습니다.")

실제로 02/server.py를 실행한 뒤, 10초동안 아무것도 안하면 아래와 같이 timeout 에러를 출력하고 종료된다.

python3.13 server.py
오류가 발생했습니다: timed out
서버 소켓을 닫았습니다.

다음은 client 코드다. ConnectionRefusedError 에러가 발생하면, while 반복문으로 새롭게 소켓을 생성한 뒤, 1초마다 연결을 재시도한다.

import socket
import time

timeout_duration = 10  # 총 대기 시간 (초)
start_time = time.time() # 시작 시간 기록

# 반복문을 돌면서 소켓을 신규로 생성해서 연결 시도
while True:
    try:
        client_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

        # 타임아웃 설정 (연결 과정 자체가 느린 경우를 대비)
        client_socket.settimeout(5)

        client_socket.connect(('127.0.0.1', 30000))
        print("서버에 연결 시도...")

        # 연결 성공 시 반복문 탈출
        break
    except ConnectionRefusedError:
        print("서버에 연결할 수 없습니다. 1초 후 재시도 합니다.")

        # 재시도 하는 로직 추가
        time.sleep(1)
        if time.time() - start_time > timeout_duration:
            print(f"{timeout_duration}초를 초과해서 종료합니다.")
            break
    except Exception as e:
        print(f"오류가 발생했습니다: {e}")
    finally:
        client_socket.close()

# 연결 성공 후 로직 (예: client_socket이 닫히지 않은 경우)
if client_socket and client_socket.fileno() != -1:
    # 여기서 데이터 통신 로직 수행
    try:
        # 예시: 데이터 전송
        # client_socket.sendall(b'Hello')
        pass
    finally:
        client_socket.close()

02/client.py를 먼저 실행한 후, 02/server.py를 실행하면 아래와 같이 재시도 하다가 연결에 성공하고, 연결을 종료한다.

언제 에러가 발생할 수 있나?

02/server.py는 10초 동안 소켓을 열어두고 대기한 뒤, 연결이 없으면 종료한다. 서버가 열었던 소켓을 닫고 종료했는데, client가 11초 뒤에 연결을 시도하면 당연히 에러가 발생할 것이다.

다음 글에서는...

위 상황에서 실제로 Wireshark를 이용해 실제 패킷을 분석해본다.

• node : https://opentelemetry.io/docs/languages/js/getting-started/nodejs/
• next : https://www.checklyhq.com/blog/in-depth-guide-to-monitoring-next-js-apps-with-opentelemetry/
• sdk 변수 : https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/
• 소스코드 레포 : https://github.com/kyeongjun-dev/nodejs-otel

실행

로컬에서 콘솔로 확인

레포의 README의 내용을 따라서 진행하시면 됩니다.

trace를 tempo로 전송한 뒤, grafana로 시각화

소스코드 레포를 clone한 뒤, docker-compose up --build 명령어를 실행합니다.

docker-compose up --build

localhost:3003/?foo=bar로 트래픽을 전송한 뒤, grafana(localhost:3000)으로 접속해서 Explore 메뉴로 이동한 뒤, 서비스명을 my-nodejs(docker-compose.yaml 파일에서 환경변수 OTEL_SERVICE_NAME로 지정한 값)로 검색하면 아래와 같이 수집되는 trace 확인이 가능합니다.

아래 명령어로 데모 앱을 생성할 수 있고, 자세한 건 레포의 README에 적어두었습니다.

npx create-next-app@latest my-app --yes

otel 관련 npm 패키지를 설치하고, my-app-docker/instrumentation.ts, my-app-docker/instrumentation.node.ts 파일이 설정에 필요한 전부입니다.

그리고 docker-compose.yaml의 nodejs 서비스 부분의 환경변수 설정에 otlp 관련 환경변수를 간단히 지정할 수 있습니다. (instrumentation.ts 코드에서도 설정이 가능하지만, 더 번거롭다고 생각합니다.)

@vercel/otel 미사용 이유

일단 유료버전이 존재하며, kubernetes 환경에 배포했을 때, service의 헬스체크마다 불필요한 로그가 발생합니다. 별도 로직으로 수집을 비활성화할 수는 있지만, 굳이라는 생각이 들어서 native otel 패키지만으로 trace 수집이 가능하도록 했습니다.

log에서 trace id 확인하기

실제 nextjs 데모앱에 localhost:3001에 접근하면 아래와 같은 로그가 출력됩니다.

 GET / 200 in 1197ms (compile: 1125ms, render: 72ms)

위 로그는 nextjs 자체에서 남기는 로그라서 trace id가 instrumentation.node.ts의 콘솔 오버라이딩이 안됩니다. 간단하게라도 테스트를 하려면, my-app-docker/app/page.tsx파일의 Home()에 임의로 console 로그를 찍습니다.

import Image from "next/image";

export default function Home() {
  console.log("Testing Trace ID inside Component");
  return (
(생략)

그러면 아래와 같이 trace id가 포함된 로그 확인이 가능합니다.

npm run dev

> my-app-docker@0.1.0 dev
> next dev

 ⚠ Port 3000 is in use by process 49870, using available port 3001 instead.
[baseline-browser-mapping] The data in this module is over two months old.  To ensure accurate Baseline data, please update: `npm i baseline-browser-mapping@latest -D`
   ▲ Next.js 16.0.5 (Turbopack)
   - Local:         http://localhost:3001
   - Network:       http://192.168.219.167:3001

 ✓ Starting...
 ✓ Ready in 922ms
trace_id=3b77cd2b9b0ea27b725003a449f46141 Testing Trace ID inside Component
trace_id=91fda6f8fcab43ff7309be3c6c756fc7 Testing Trace ID inside Component
 GET / 200 in 1197ms (compile: 1125ms, render: 72ms)

깃허브 링크 및 repo의 README 참고 가능

개요

몽고디비의 hidden member

hidden member는 간략히 설명하자면 클라이언트에게 노출되지 않는 멤버다. (ex 데이터 분석용으로 사용 가능)

mongodb에서 read member를 추가할 때, data의 sync 과정이 이루어진다. 그런데 sync 해야하는 데이터량이 너무 크면, 데이터 sync가 끝나지 않았어도 client에서 연결 및 쿼리 결과가 OK로 반환된다.

따라서 read member 노드를 추가할 때 hidden node로 추가하는 방식을 사용할 수 있다. hidden으로 추가한 후, read로 변경할 수 있다

percona operator for mongodb

쿠버네티스 클러스터에서 operator 패턴으로 mongodb 클러스터를 구축해서 사용할 수 있게 해주는 툴이다. 구성 가능한 구성은 2가지다 - 링크

• replica set 구성
• sharding 구성 ### hidden 기능 추가 비용 절감을 위해 몽고디비도 충분히 Auto Scaling을 적용할 수 있을것 같아서, 프로젝트를 진행한 적이 있는데 데이터가 전부 sync되지 않았는데 client에게 OK query result를 보내서 중지한 적이 있다. 그래서 hidden 노드를 추가하는 기능을 추가하면 어떨가 했는데 작년 24년 9월에 이미 기능추가 요청이 있었다 ([링크](https://github.com/percona/percona-server-mongodb-operator/issues/1663)) PSMDB Operator v1.21.0 에서 해당 기능이 추가됐다.

테스트

github repo의 README를 참고

kind로 클러스터 생성

cluster.yaml 파일 생성

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  image: kindest/node:v1.32.8
  # port forward 27017 on the host to 27017 on this node
  extraPortMappings:
  - containerPort: 27017
    hostPort: 27017
    # optional: set the bind address on the host
    # 0.0.0.0 is the current default
    listenAddress: "0.0.0.0"
    # optional: set the protocol to one of TCP, UDP, SCTP.
    # TCP is the default
    protocol: TCP
- role: worker
  image: kindest/node:v1.32.8
  labels:
    topology.kubernetes.io/zone: ap-northeast-2a
- role: worker
  image: kindest/node:v1.32.8
  labels:
    topology.kubernetes.io/zone: ap-northeast-2b
- role: worker
  image: kindest/node:v1.32.8
  labels:
    topology.kubernetes.io/zone: ap-northeast-2c

설치 (링크)

namespace 생성

kubectl create ns mongodb

helm repo 설치

helm repo add percona https://percona.github.io/percona-helm-charts/
helm repo update

psmdb operator 설치 (테스트 당시 최신버전 1.21.0)

helm search repo percona/psmdb-operator --versions
helm pull percona/psmdb-operator --version 1.21.0
tar xvf psmdb-operator-1.21.0.tgz
helm install psmdb-operator charts/psmdb-operator -f values/psmdb-operator/values.yaml

psmdb db 설치

helm search repo percona/psmdb-db --versions
helm pull percona/psmdb-db --version 1.21.0
tar xvf psmdb-db-1.21.0.tgz
helm install cluster-1 charts/psmdb-db -f values/psmdb-db/values.yaml

mongodb 접속 및 상태확인

psmdb를 기본 설정으로 설치하면, 여러 secret이 생성된다.

kubectl get secret
NAME                                        TYPE                 DATA   AGE
cluster-1-psmdb-db-mongodb-encryption-key   Opaque               1      6m2s
cluster-1-psmdb-db-mongodb-keyfile          Opaque               1      6m2s
cluster-1-psmdb-db-secrets                  Opaque               10     6m2s
cluster-1-psmdb-db-ssl                      kubernetes.io/tls    3      6m2s
cluster-1-psmdb-db-ssl-internal             kubernetes.io/tls    3      6m2s
internal-cluster-1-psmdb-db-users           Opaque               20     6m2s
sh.helm.release.v1.cluster-1.v1             helm.sh/release.v1   1      6m2s
sh.helm.release.v1.psmdb-operator.v1        helm.sh/release.v1   1      7m42s

여기서 접속에 필요한 정보는 <클러스터 이름>-psmdb-db-secrets에서 확인할 수 있다. (MONGODB_CLUSTER_ADMIN_USER)

kubectl get secret cluster-1-psmdb-db-secrets -o go-template='{{range $k,$v := .data}}{{printf "%s: " $k}}{{if not $v}}{{$v}}{{else}}{{$v | base64decode}}{{end}}{{"\n"}}{{end}}'
MONGODB_BACKUP_PASSWORD: xjDLAXAfaEndA1W8w
MONGODB_BACKUP_USER: backup
MONGODB_CLUSTER_ADMIN_PASSWORD: ShdEOvY3nSLB1LXElmr
MONGODB_CLUSTER_ADMIN_USER: clusterAdmin
MONGODB_CLUSTER_MONITOR_PASSWORD: FLm5VAFHutGNyLOgE
MONGODB_CLUSTER_MONITOR_USER: clusterMonitor
MONGODB_DATABASE_ADMIN_PASSWORD: itUSHr20UuUo2M4Ih
MONGODB_DATABASE_ADMIN_USER: databaseAdmin
MONGODB_USER_ADMIN_PASSWORD: NbcMoEkJe7NeQ2QrVIC
MONGODB_USER_ADMIN_USER: userAdmin

실행된 pod를 확인하고

kubectl get pod   
NAME                              READY   STATUS    RESTARTS   AGE
cluster-1-psmdb-db-rs0-0          1/1     Running   0          6m29s
cluster-1-psmdb-db-rs0-1          1/1     Running   0          5m38s
cluster-1-psmdb-db-rs0-2          1/1     Running   0          4m54s
psmdb-operator-7d9c58954c-x9dzd   1/1     Running   0          8m9s

파드 하나에 접속한다. 0번 파드가 웬만하면 primary일 것이다.

kubectl exec -it cluster-1-psmdb-db-rs0-0 -- mongosh "mongodb://clusterAdmin:ShdEOvY3nSLB1LXElmr@localhost:27017/admin"
Defaulted container "mongod" out of: mongod, mongo-init (init)
Current Mongosh Log ID: 68fdc70b19fc7f4ffc248377
Connecting to:          mongodb://<credentials>@localhost:27017/admin?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.6
Using MongoDB:          8.0.12-4
Using Mongosh:          2.5.6
mongosh 2.5.8 is available for download: https://www.mongodb.com/try/download/shell

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

rs0 [direct: primary] admin>

rs.status()로 현재 레플리카셋의 상태를 확인할 수 있다

rs0 [direct: primary] admin> rs.status().members
[
  {
    _id: 0,
    name: 'cluster-1-psmdb-db-rs0-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    health: 1,
    state: 1,
    stateStr: 'PRIMARY',
  },
  {
    _id: 1,
    name: 'cluster-1-psmdb-db-rs0-1.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    health: 1,
    state: 2,
    stateStr: 'SECONDARY',
  },
  {
    _id: 2,
    name: 'cluster-1-psmdb-db-rs0-2.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    health: 1,
    state: 2,
    stateStr: 'SECONDARY',
  }
]

hidden 노드 추가해보기

먼저 CR 목록에서 현재 설치된 psmdb-db 상태를 확인할 수 있다.

kubectl get perconaservermongodbs.psmdb.percona.com
NAME                 ENDPOINT                                           STATUS   AGE
cluster-1-psmdb-db   cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local   ready    18m

yaml로 출력하면 아래와 같다.

kubectl get perconaservermongodbs.psmdb.percona.com -oyaml
apiVersion: v1
items:
- apiVersion: psmdb.percona.com/v1
  kind: PerconaServerMongoDB
  metadata:
    annotations:
      meta.helm.sh/release-name: cluster-1
      meta.helm.sh/release-namespace: mongodb
    creationTimestamp: "2025-10-26T06:49:04Z"
    finalizers:
    - percona.com/delete-psmdb-pods-in-order
    generation: 1
    labels:
      app.kubernetes.io/instance: cluster-1
      app.kubernetes.io/managed-by: Helm
      app.kubernetes.io/name: psmdb-db
      app.kubernetes.io/version: 1.21.0
      helm.sh/chart: psmdb-db-1.21.0
    name: cluster-1-psmdb-db
    namespace: mongodb
    resourceVersion: "2733"
    uid: 4fc410d9-b4d7-47b8-bb0f-03ea8c8056a4
  spec:
    backup:
      enabled: false
      image: percona/percona-backup-mongodb:2.11.0
      pitr:
        enabled: false
    crVersion: 1.21.0
    enableVolumeExpansion: false
    image: percona/percona-server-mongodb:8.0.12-4
    imagePullPolicy: Always
    logcollector:
      enabled: false
      image: percona/fluentbit:4.0.1
      resources:
        requests:
          cpu: 200m
          memory: 100M
    multiCluster:
      enabled: false
    pause: false
    pmm:
      enabled: false
      image: percona/pmm-client:3.4.1
      serverHost: monitoring-service
    replsets:
    - affinity:
        antiAffinityTopologyKey: kubernetes.io/hostname
      arbiter:
        affinity:
          antiAffinityTopologyKey: kubernetes.io/hostname
        enabled: false
        resources:
          limits:
            cpu: 600m
            memory: 1Gi
          requests:
            cpu: 300m
            memory: 1Gi
        size: 1
      expose:
        enabled: false
        type: ClusterIP
      hidden:
        affinity:
          antiAffinityTopologyKey: kubernetes.io/hostname
        enabled: false
        podDisruptionBudget:
          maxUnavailable: 1
        resources:
          limits:
            cpu: 600m
            memory: 1Gi
          requests:
            cpu: 300m
            memory: 1Gi
        size: 2
        volumeSpec:
          persistentVolumeClaim:
            resources:
              requests:
                storage: 3Gi
      name: rs0
      nonvoting:
        affinity:
          antiAffinityTopologyKey: kubernetes.io/hostname
        enabled: false
        podDisruptionBudget:
          maxUnavailable: 1
        resources:
          limits:
            cpu: 600m
            memory: 1Gi
          requests:
            cpu: 300m
            memory: 1Gi
        size: 3
        volumeSpec:
          persistentVolumeClaim:
            resources:
              requests:
                storage: 3Gi
      podDisruptionBudget:
        maxUnavailable: 1
      resources:
        limits:
          cpu: 600m
          memory: 1Gi
        requests:
          cpu: 300m
          memory: 1Gi
      size: 3
      volumeSpec:
        persistentVolumeClaim:
          resources:
            requests:
              storage: 3Gi
    secrets:
      users: cluster-1-psmdb-db-secrets
    sharding:
      balancer:
        enabled: true
      configsvrReplSet:
        affinity:
          antiAffinityTopologyKey: kubernetes.io/hostname
        expose:
          enabled: false
          type: ClusterIP
        podDisruptionBudget:
          maxUnavailable: 1
        resources:
          limits:
            cpu: 600m
            memory: 1Gi
          requests:
            cpu: 300m
            memory: 1Gi
        size: 3
        volumeSpec:
          persistentVolumeClaim:
            resources:
              requests:
                storage: 3Gi
      enabled: false
      mongos:
        affinity:
          antiAffinityTopologyKey: kubernetes.io/hostname
        expose:
          type: ClusterIP
        podDisruptionBudget:
          maxUnavailable: 1
        resources:
          limits:
            cpu: 600m
            memory: 1Gi
          requests:
            cpu: 300m
            memory: 1Gi
        size: 3
    unmanaged: false
    unsafeFlags:
      backupIfUnhealthy: false
      mongosSize: false
      replsetSize: false
      terminationGracePeriod: false
      tls: false
    updateStrategy: SmartUpdate
    upgradeOptions:
      apply: disabled
      schedule: 0 2 * * *
      setFCV: false
      versionServiceEndpoint: https://check.percona.com

이제 설치할 때 사용한 helm values 파일을 수정해서 적용해본다. 먼저 레플리카셋 멤버를 3대에서 2대로 줄여보자. 기본적으로 레플리카셋의 파드는 홀수여야 하므로, unsafeFlasgs의 replesetSize 값을 true로 변경해준다.

replsets:
  rs0:
    name: rs0
    size: 2 # 3에서 2로 변경

unsafeFlags:
  tls: false
  replsetSize: true

수정 사항을 helm diff로 확인해본 뒤, 적용한다.

helm diff upgrade cluster-1 charts/psmdb-db -f values/psmdb-db/values.yaml | grep -E '^(\+|-)'     
-     size: 3
+     size: 2

mongosh 쉘에 접속해서 보면, 3번째 rs0 멤버가 제거된 것을 확인할 수 있다.

rs0 [direct: primary] admin> rs.status().members
[
  {
    _id: 0,
    name: 'cluster-1-psmdb-db-rs0-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    health: 1,
    state: 1,
    stateStr: 'PRIMARY',
  },
  {
    _id: 1,
    name: 'cluster-1-psmdb-db-rs0-1.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    health: 1,
    state: 2,
    stateStr: 'SECONDARY',
  }
]

이제 hidden 노드 추가를 위해 아래와 같이 values 파일을 수정해주자.

    hidden:
      enabled: true
#      podSecurityContext: {}
#      containerSecurityContext: {}
      size: 1

변경사항을 적용한 후, hidden 파드가 추가되는 것을 확인할 수 있다.

kubectl get pod                                           
NAME                              READY   STATUS    RESTARTS   AGE
cluster-1-psmdb-db-rs0-0          1/1     Running   0          34m
cluster-1-psmdb-db-rs0-1          1/1     Running   0          33m
cluster-1-psmdb-db-rs0-hidden-0   0/1     Running   0          11s
psmdb-operator-7d9c58954c-x9dzd   1/1     Running   0          36m

실제 rs.conf()에서 확인해보면 hidden 값이 true임을 확인할 수 있다.

rs0 [direct: primary] admin> rs.conf().members
[
  {
    _id: 0,
    host: 'cluster-1-psmdb-db-rs0-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker',
      podName: 'cluster-1-psmdb-db-rs0-0'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 1,
    host: 'cluster-1-psmdb-db-rs0-1.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker3',
      podName: 'cluster-1-psmdb-db-rs0-1'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 2,
    host: 'cluster-1-psmdb-db-rs0-hidden-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: true,
    priority: 0,
    tags: {
      podName: 'cluster-1-psmdb-db-rs0-hidden-0',
      serviceName: 'cluster-1-psmdb-db',
      hidden: 'true',
      nodeName: '1.32-worker2'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  }
]

hidden 멤버를 secondary로 변경하기

mongosh 쉘에 접근한 상태에서 rs.conf() 를 변수에 저장한다.

rs0 [direct: primary] admin> cfg = rs.conf()

hidden 값을 변경한다.

rs0 [direct: primary] admin> cfg.members[2].hidden=false
false

cfg 설정을 적용한다.

rs0 [direct: primary] admin> rs.reconfig(cfg)

rs.conf() 확인

rs0 [direct: primary] admin> rs.conf().members
[
  {
    _id: 0,
    host: 'cluster-1-psmdb-db-rs0-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker',
      podName: 'cluster-1-psmdb-db-rs0-0'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 1,
    host: 'cluster-1-psmdb-db-rs0-1.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker3',
      podName: 'cluster-1-psmdb-db-rs0-1'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 2,
    host: 'cluster-1-psmdb-db-rs0-hidden-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 0,
    tags: {
      podName: 'cluster-1-psmdb-db-rs0-hidden-0',
      serviceName: 'cluster-1-psmdb-db',
      hidden: 'true',
      nodeName: '1.32-worker2'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  }
]

위 상태에서 다시 replset 개수를 3으로 변경해본다.

replsets:
  rs0:
    name: rs0
    size: 3
---
helm upgrade cluster-1 charts/psmdb-db -f values/psmdb-db/values.yaml

파드가 총 4개가 된 것을 확인할 수 있다.

kubectl get pod                                    
NAME                              READY   STATUS    RESTARTS   AGE
cluster-1-psmdb-db-rs0-0          1/1     Running   0          88m
cluster-1-psmdb-db-rs0-1          1/1     Running   0          87m
cluster-1-psmdb-db-rs0-2          1/1     Running   0          102s
cluster-1-psmdb-db-rs0-hidden-0   1/1     Running   0          54m
psmdb-operator-7d9c58954c-x9dzd   1/1     Running   0          90m

그리고 rs.conf()를 확인해보면, hidden이 전부 false인 것을 확인할 수 있다. 여기서 rs.conf()와 CR로 적용되는 값은 별도로 유지되는 것을 확인할 수 있다.

rs0 [direct: primary] admin> rs.conf().members
[
  {
    _id: 0,
    host: 'cluster-1-psmdb-db-rs0-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      podName: 'cluster-1-psmdb-db-rs0-0',
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 1,
    host: 'cluster-1-psmdb-db-rs0-1.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 2,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker3',
      podName: 'cluster-1-psmdb-db-rs0-1'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 2,
    host: 'cluster-1-psmdb-db-rs0-hidden-0.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 0,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      hidden: 'true',
      nodeName: '1.32-worker2',
      podName: 'cluster-1-psmdb-db-rs0-hidden-0'
    },
    secondaryDelaySecs: Long('0'),
    votes: 1
  },
  {
    _id: 3,
    host: 'cluster-1-psmdb-db-rs0-2.cluster-1-psmdb-db-rs0.mongodb.svc.cluster.local:27017',
    arbiterOnly: false,
    buildIndexes: true,
    hidden: false,
    priority: 0,
    tags: {
      serviceName: 'cluster-1-psmdb-db',
      nodeName: '1.32-worker2',
      podName: 'cluster-1-psmdb-db-rs0-2'
    },
    secondaryDelaySecs: Long('0'),
    votes: 0
  }
]

정리 및 결론

• 쿠버네티스 환경의 특성을 이용해서 몽고디비도 스케일링이 가능할 것 같다.
• 쿠버네티스 환경에서 몽고디비를 직접 구성해서 관리하기는 어렵기에 Operator를 사용하면 간편하다.
• Operator를 이용할 때, 오토스케일링을 할 경우 신규 secondary에 데이터 동기화가 안되었음에도 쿼리가 성공하는 이슈가 있었다.
• psmdb-operator 1.21부터 hidden 노드를 추가할 수 있게 되었다.
• hidden 노드를 추가한 뒤, 일정 시간 뒤에 rs.conf(), rs.reconfig()를 이용해 hidden 값을 false로 변경해주면 데이터 동기화 이슈를 방지할 수 있다.
• hidden 멤버 외에도 non-voting 멤버도 존재한다. (예전에는 레플리카셋 3개 노드만 pvc를 붙이고, 오토스케일링으로 스케일아웃되는 파드는 pvc없이 로컬 volume을 사용하는 non-voting으로 진행했었다.)

참고사이트

• tempo cli 사용법 docs : https://grafana.com/docs/tempo/latest/operations/tempo_cli/
• tempo cli 바이너리 파일 다운로드하는 release 페이지 : https://github.com/grafana/tempo/releases/

  개요

  tempo에서 크기가 큰 trace를 검색하면, max_bytes_per_trace 크기를 초과하는 경우 trace exceeds max size에러로 검색이 불가능합니다 무작정 max_bytes_per_trace를 올리는 것보다는 적절하게 값을 조정해주는게 좋기에 trace 크기를 tempo-cli를 이용해 확인합니다

설치 및 trace id 확인

https://github.com/kyeongjun-dev/monitoring/tree/feat/docker-compose_tempo-cli/example/docker-compose-springboot-native-histogram-local_tempo-cli repo를 clone하고 위 디렉토리로 이동 후, docker-compose up -d 명령어를 실행한 뒤에 루트디렉토리로 이동하여 sh curl-springboot-delay.sh 8080로 springboot 앱에 trace를 발생시킵니다

localhost:3000 그라파나로 접속하여 trace id를 임의로 확인합니다 (여기서는 3e5d8cc884b51d1b488a821fb7f3b29 사용)

tempo-cli 실행

docker-compose up -d 명령어를 수행한 디렉토리에서 아래 아래 사진에 표시된 (1)번과 같이 tempo-data 디렉토리를 확인할 수 있습니다

clone한 root 디렉토리에 tempo-cli 파일이 있는데, 해당 파일(amd64)을 이용하여 tempo-cli를 실행할 수 있습니다

arm 등 arch가 맞지 않는겨우, tempo github의 release 페이지에서 알맞은 tar 파일을 받아서 압축을 해제하면, tempo-cli 파일이 들어있습니다 https://github.com/grafana/tempo/releases/tag/v2.7.1

./tempo-cli query trace-summary 3e5d8cc884b51d1b488a821fb7f3b29 single-tenant --backend=local --bucket=./example/docker-compose-springboot-native-histogram-local_tempo-cli/tempo-data/blocks/

루트 디렉토리를 기준으로 ./tempo-cli query trace-summary 명령어를 실행합니다

• 325d~ : trace id
• single-tenant : tempo-data/blocks/single-tenant 디렉토리 이름
• backend : local (local, s3, gcs 등 설정 가능)
• bucket : 검색할 디렉토리 위치

실행결과는 아래와 같습니다 : 탐색한 block 개수, trace에 포함된 Span 개수, trcace 크기 등

total blocks to search:  8
....0....Number of blocks: 2 
Span count: 2 
Trace size: 2944 B 
Trace duration: 5 seconds 
Root service name: demo 
Root span info:
(*v1.Span)(0xc0004864b0)({
 TraceId: ([]uint8) (len=16 cap=16) {
  00000000  03 e5 d8 cc 88 4b 51 d1  b4 88 a8 21 fb 7f 3b 29  |.....KQ....!..;)|
 },
 SpanId: ([]uint8) (len=8 cap=8) {
  00000000  5d df c3 c6 d7 de f2 f2                           |].......|
 },
 TraceState: (string) "",
 ParentSpanId: ([]uint8) {
 },
 Flags: (uint32) 0,
 Name: (string) (len=10) "GET /delay",
 Kind: (v1.Span_SpanKind) 2,
 StartTimeUnixNano: (uint64) 1742478694709420660,
 EndTimeUnixNano: (uint64) 1742478699710892523,
 Attributes: ([]*v1.KeyValue) (len=15 cap=16) {
  (*v1.KeyValue)(0xc00079d4d0)({
   Key: (string) (len=10) "http.route",
   Value: (*v1.AnyValue)(0xc000893650)({
    Value: (*v1.AnyValue_StringValue)(0xc000893660)({
     StringValue: (string) (len=6) "/delay"
    })
   })
  }),
(생략)
DroppedAttributesCount: (uint32) 0,
 Events: ([]*v1.Span_Event) <nil>,
 DroppedEventsCount: (uint32) 0,
 Links: ([]*v1.Span_Link) <nil>,
 DroppedLinksCount: (uint32) 0,
 Status: (*v1.Status)(0xc00079d650)({
  Message: (string) "",
  Code: (v1.Status_StatusCode) 0
 })
})
top frequent service.names: 
[demo    ]

마치며

https://grafana.com/docs/tempo/latest/operations/tempo_cli/ 위 링크를 참고하면 다양한 tempo-cli 기능을 확인할 수 있습니다 s3에 tempo 데이터가 저장되는 경우, 옵션만 다르게하여 검색이 가능합니다 (minio를 docker-compose로 구성해서 tempo cli를 사용하면, server gave HTTP response to HTTPS client 에러가 발생하는데, tempo cli 자체가 https로 요청을 보내서 그런것으로 생각되지만 보통은 s3에 저장을 할 것이기에... 깊이 파보지는 않았습니다)

해당 글에서는 java의 Span 데이터를 Tempo로 수집해서, Tempo의 metrics-generator로 Metrics 데이터로 변환 후 Prometheus로 전송하는 방법을 다룹니다 여기서 Prometheus로 전송하는 Metrics 데이터는 Native Histogram 입니다 구성도는 아래와 같습니다

repo clone

레포에 있는 helm chart와 작성된 helmfile을 주로 이용합니다

git clone https://github.com/kyeongjun-dev/monitoring.git
cd monitoring/example/docker-compose-springboot-native-histogram

docker-compose 실행

docker-compose.yaml 파일을 이용하여 컨테이너를 실행합니다

docker-compose up -d

가끔 wsl 환경에서 아래와 같이 port를 사용할 수 없다고 뜨는데,

Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:3000 -> 127.0.0.1:0: listen tcp 0.0.0.0:3000: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

다음 링크를 참고하여 port를 해제할 수 있습니다 : https://not-to-be-reset.tistory.com/638

실행되는 컨테이너는 tempo, springboot, grafana, prometheus, opentelemetry-collector 총 5개 입니다 - 중간의 tempo가 하나 더 있는건 init 컨테이너 입니다

 docker ps -a | grep docker-compose
c175a5ed0b26   grafana/tempo:2.7.1                                                "/tempo -config.file…"   2 minutes ago   Up 2 minutes               0.0.0.0:4675->3200/tcp, 0.0.0.0:4676->4317/tcp   docker-compose-springboot-native-histogram-tempo-1
6cff2baaf180   kyeongjundev/springboot:39e2e243b5ddd14f47c35a91f00c068aef13b6ab   "java -javaagent:ope…"   2 minutes ago   Up 2 minutes               0.0.0.0:8080->8080/tcp                           docker-compose-springboot-native-histogram-springboot-1
80d8a37fdab1   grafana/grafana:11.0.0                                             "/run.sh"                2 minutes ago   Up 2 minutes               0.0.0.0:3000->3000/tcp                           docker-compose-springboot-native-histogram-grafana-1
5bf01910095e   grafana/tempo:2.7.1                                                "chown 10001:10001 /…"   2 minutes ago   Exited (0) 2 minutes ago                                                    docker-compose-springboot-native-histogram-init-1
5b666c812370   prom/prometheus:v3.1.0                                             "/bin/prometheus --c…"   2 minutes ago   Up 2 minutes               0.0.0.0:9090->9090/tcp                           docker-compose-springboot-native-histogram-prometheus-1
1248a61fe2fb   otel/opentelemetry-collector:0.86.0                                "/otelcol --config=/…"   2 minutes ago   Up 2 minutes               4317/tcp, 55678-55679/tcp                        docker-compose-springboot-native-histogram-otel-collector-1

설정파일 확인

tempo

tempo.yaml 파일에 아래와 같이 metrics-generator를 활성화 했습니다 여기서 중요한 부분은 span-metrics 입니다. 해당 processor가 span 데이터를 metrics 데이터로 변환합니다 generate_native_histograms에는 [native, classic, both] 가 설정 가능합니다

overrides:
  defaults:
    metrics_generator:
      processors: [service-graphs, span-metrics, local-blocks] # enables metrics generator
      generate_native_histograms: native

prometheus

prometheus.yaml 파일에서는 필수 설정은 아니지만 prometheus와 tempo의 metrics 데이터를 수집하도록 설정 했습니다.

global:
  scrape_interval:     15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: [ 'localhost:9090' ]
  - job_name: 'tempo'
    static_configs:
      - targets: [ 'tempo:3200' ]

docker-compose.yaml 파일의 명령어에서 prometheus의 remote write, native histogram 기능을 활성화 했습니다 - prometheus.yaml 파일에서 활성화해도 됩니다

...
  prometheus:
    image: prom/prometheus:v3.1.0
    command:
      - --config.file=/etc/prometheus.yaml
      - --web.enable-remote-write-receiver
      - --enable-feature=exemplar-storage
      - --enable-feature=native-histograms
    volumes:
      - ./prometheus.yaml:/etc/prometheus.yaml
    ports:
      - "9090:9090"
...

otel collector

otel-collector.yaml에서는 최소한의 설정으로 springboot에서 전달받은 trace를 tempo로 전송하도록 설정했습니다 exporters에 logging을 설정하면, 실제 trace가 어떻게 전달되는지 otel-collector 컨테이너 로그로 확인할 수 있습니다

receivers:
  otlp:
    protocols:
      grpc:
exporters:
  otlp:
    endpoint: tempo:4317
    tls:
      insecure: true
  logging:
      verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlp, logging]

트래픽 생성 및 prometheus 확인

웹 브라우저에서 아래 endpoint의 8080 포트로 직접 접속해도 되고, clone한 repo의 루트에 있는 sh curl-springboot-delay.sh 스크립트를 실행해도 됩니다

localhost:8080
localhost:8080/ip
localhost:8080/delay?delay=1

sh curl-springboot-delay.sh 8080

prometheus의 NodePort 30080으로 접속하여 쿼리를 실행합니다

traces_spanmetrics_latency

아래와 같이 native-histogram으로 수집된 metrics 데이터를 확인할 수 있습니다