후니 님의 블로그

Terraform 입문클릭으로 만들던 인프라를 코드로 관리하기

0321ljh — Fri, 15 May 2026 14:56:59 +0900

☁️ Infrastructure as Code

AWS 콘솔 없이도 동일한 인프라를 반복 재현하는 법
개념부터 실전 패턴, 실수 방지까지

2025년 5월 ️ Terraform · IaC · DevOps

왜 Terraform을 써야 하는가
핵심 개념 4가지 — Provider / Resource / State / Plan+Apply
기본 명령어와 동작 흐름
State와 Remote Backend
변수 · 출력 · 모듈
절대로 코드에 넣으면 안 되는 것들
변경 요청 6단계 워크플로우
Plan 결과 직접 분석해보기
추가로 알아야 할 개념들
실무 도구 생태계
정리 & 체크리스트

Part 1

왜 Terraform을 써야 하는가

어느 스타트업의 월요일 아침, 팀장님이 이렇게 메시지를 보냈다고 상상해 보세요.

실제 상황

"스테이징 환경 그대로 프로덕션에 한 벌 더 만들어주세요. 이번 주 안에 가능하시죠?"
— 스테이징은 6개월 전 누군가가 AWS 콘솔에서 클릭클릭 만든 환경. 문서는 없음.

VPC, Subnet, Security Group, RDS, EC2, ALB, IAM Role … 하나씩 콘솔 열어서 비교하고 다시 클릭으로 만드는 것, 가능하긴 합니다. 그런데 그 과정에서 누락이나 실수가 생기면? 다음에 또 같은 요청이 들어오면?

콘솔 관리 vs IaC — 무엇이 다른가

구분	콘솔 관리	IaC (Terraform)
핵심 질문	지금 무엇을 만들 것인가?	어떤 상태를 유지할 것인가?
변경 이력	❌ 남지 않음	✅ Git에 기록됨
환경 복제	수작업 반복	동일 코드로 반복 가능
코드 리뷰	❌ 불가	✅ PR 리뷰 가능
실수 회복	어려움	코드 되돌리기로 복구
환경 동기화	dev/prod 설정이 서서히 어긋남	같은 코드로 동일 보장

✅ 한 줄 정의

Terraform은 HashiCorp가 만든 IaC 도구로, 인프라를 HCL(HashiCorp Configuration Language) 코드로 선언하고, 현재 상태와 비교한 뒤, 변경을 안전하게 반영하는 도구입니다.

좋은 IaC의 5가지 조건

조건	왜 필요한가	어떻게
선언적	"어떤 상태가 되어야 하는지"만 표현	`resource` 블록 사용
재현 가능	같은 코드 = 같은 결과	Terraform 자체 동작
검토 가능	변경 전 영향 파악	`terraform plan`
협업 가능	팀원과 동시 작업	Remote Backend + Locking
안전	사고 시 복구 가능	Git 이력 + 백업

Part 2

핵심 개념 4가지

Provider

Terraform과 외부 서비스(AWS, GCP 등)를 연결하는 플러그인

Resource

만들거나 관리할 실제 대상 (EC2, S3, RDS 등)

State

코드와 실제 인프라를 매핑한 기록 파일 (.tfstate)

Plan / Apply

변경 계획 미리보기(plan) → 실제 반영(apply)

Provider — Terraform과 AWS를 연결하는 다리

Terraform 자체는 AWS EC2가 뭔지 모릅니다. Provider가 각 클라우드 서비스의 리소스 타입과 API 호출 방법을 알고 있습니다.

# Provider 설정 — 항상 버전을 고정하세요
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # 5.x 범위 내 최신 버전 사용
    }
  }
}

provider "aws" {
  region = "ap-northeast-2"  # 서울 리전
}main.tf

⚠️ 주의

version = "~> 5.0"은 5.x 버전만 허용한다는 뜻입니다. 버전을 고정하지 않으면 팀원마다 다른 버전으로 실행해서 예기치 않은 동작이 발생할 수 있습니다.

Resource — 관리할 대상 선언

# 형식: resource "리소스_타입" "로컬_이름" { ... }
resource "aws_s3_bucket" "logs" {
  bucket = "my-app-logs-2026"

  tags = {
    Environment = "prod"
    ManagedBy   = "terraform"
  }
}main.tf

aws_s3_bucket은 리소스 타입, logs는 이 코드 내에서 참조할 때 쓰는 이름입니다. 실제 AWS에는 bucket 값인 my-app-logs-2026로 만들어집니다.

State — Terraform의 기억

State는 Terraform이 "내가 어떤 리소스를 만들었는가"를 기록한 파일입니다. terraform.tfstate라는 JSON 파일로 저장됩니다.

// terraform.tfstate (자동 생성 — 직접 수정 금지!)
{
  "version": 4,
  "resources": [
    {
      "type": "aws_s3_bucket",
      "name": "logs",
      "instances": [
        {
          "attributes": {
            "bucket": "my-app-logs-2026",
            "arn":    "arn:aws:s3:::my-app-logs-2026"
          }
        }
      ]
    }
  ]
}terraform.tfstate

절대 금지

terraform.tfstate를 절대 Git에 커밋하지 마세요. DB 비밀번호, IAM Secret Key 등 민감 정보가 평문(plain text)으로 담겨 있습니다.

Plan / Apply — 변경의 양면

plan은 변경 예고편, apply는 실제 반영입니다. 실무에서 plan 결과를 정확히 읽는 것이 apply보다 더 중요합니다.

+ aws_instance.web       # ✅ 신규 생성 → 비용 발생
~ aws_s3_bucket.logs    #   속성 수정 (in-place)
- aws_eip.legacy        # ❌ 삭제 → 데이터 손실 위험!
-/+ aws_db_instance.main #   삭제 후 재생성 (다운타임!)plan 기호 해석

Force Replacement (-/+)

-/+는 기존 리소스를 삭제 후 새로 만든다는 뜻입니다. RDS의 db_name 변경이 대표적인 예시 — DB가 삭제되면 데이터도 함께 사라집니다. 반드시 스냅샷 백업 후 진행하세요.

Part 3

기본 명령어와 동작 흐름

명령어	역할	언제 실행?
`terraform init`	작업 디렉터리 초기화, Provider 다운로드	프로젝트 시작 시, Provider 변경 시
`terraform fmt`	코드 포맷 자동 정리	커밋 전
`terraform validate`	문법 검증	커밋 전, CI에서 자동 실행
`terraform plan`	변경 계획 미리 보기	apply 전 항상
`terraform apply`	실제 인프라 반영	plan 검토 후
`terraform destroy`	관리 중인 리소스 전체 삭제	테스트 환경 정리 시
`terraform state list`	state에 등록된 리소스 목록	state 확인 시
`terraform state mv`	리소스 이름 변경 시 state 동기화	리소스 식별자 변경 시
`terraform import`	기존 리소스를 state로 가져옴	콘솔 리소스를 IaC로 전환 시
`terraform output`	output 값 조회	apply 후 값 확인 시

전체 동작 흐름

.tf 파일 작성

HCL로 원하는 인프라 상태를 선언

↓

terraform init

Provider 다운로드, .terraform 폴더 생성

↓

terraform fmt & validate

코드 스타일 정리 + 문법 검증

↓

terraform plan

현재 state와 코드를 비교 → 변경 예고

↓

plan 결과 검토

삭제 항목, Force Replacement 여부 확인

↓

terraform apply

실제 클라우드 API 호출 → 인프라 변경 + state 업데이트

↓

다시 plan → "No changes"

코드와 실제가 일치함을 확인

실습: Random Provider로 흐름 체험하기

AWS 계정 없이도 Terraform 명령어 흐름을 연습할 수 있습니다.

terraform {
  required_providers {
    random = {
      source  = "hashicorp/random"
      version = "~> 3.0"
    }
  }
}

resource "random_id" "server" {
  byte_length = 8
}

output "server_id" {
  value = random_id.server.hex
}main.tf

# 순서대로 실행
$ mkdir terraform-practice && cd terraform-practice
$ terraform init
$ terraform plan
$ terraform apply
$ cat terraform.tfstate   # state 파일 확인
$ terraform destroyterminal

Part 4

State와 Remote Backend

State가 꼬이면 벌어지는 일

상황	결과
state 파일 분실	Terraform이 기존 리소스를 "없는 것"으로 인식 → 중복 생성
state와 실제 인프라 불일치	plan 결과가 예상과 전혀 다르게 나옴
두 명이 동시에 apply	state 파일 손상 (race condition)
state를 Git에 커밋	DB 비밀번호 등이 GitHub에 평문 노출

Remote Backend — 팀 협업의 필수 조건

혼자 쓸 때는 로컬 state 파일로도 되지만, 팀이 함께 작업한다면 Remote Backend는 필수입니다. 가장 흔한 조합은 AWS S3 + DynamoDB입니다.

terraform {
  backend "s3" {
    bucket         = "my-terraform-state"
    key            = "prod/terraform.tfstate"
    region         = "ap-northeast-2"
    encrypt        = true                       # S3 저장 시 암호화
    dynamodb_table = "terraform-state-lock"     # 동시 실행 방지 (Locking)
  }
}backend.tf

State Locking — 동시 실행 방지

[10:00] 개발자 A: terraform apply 시작
        → DynamoDB에 lock 획득

[10:01] 개발자 B: terraform apply 시도
        → Error: Error acquiring the state lock
        → 대기 또는 중단

[10:05] 개발자 A: apply 완료 → lock 해제
[10:06] 개발자 B: 재시도 가능State Locking 흐름

Drift — 코드와 실제 인프라가 어긋날 때

⚠️ Drift란?

Terraform으로 만든 리소스를 콘솔에서 직접 수정하면 코드와 실제가 달라집니다. 다음 plan 때 의도치 않은 변경이 나타납니다.

# 시나리오
1. Terraform으로 EC2 생성 (코드: t3.medium)
2. 콘솔에서 t3.large로 수동 변경  ← Drift 발생!
3. 다음 terraform plan 결과:
   ~ aws_instance.web
     ~ instance_type: "t3.large" → "t3.medium"
4. 모르고 apply 하면 t3.medium으로 되돌려짐Drift 예시

원칙: Terraform으로 만든 리소스는 콘솔에서 수정하지 않는다.
긴급 상황으로 콘솔 수정이 불가피했다면, 반드시 코드에도 동일하게 반영

추가: terraform import

기존에 콘솔로 만든 리소스를 Terraform 관리로 가져오고 싶을 때 씁니다.

# 콘솔에서 만든 S3 버킷을 state로 가져오기
$ terraform import aws_s3_bucket.logs my-app-logs-2026

# 가져온 뒤에는 코드를 state에 맞게 작성해야 합니다
$ terraform plan  # "No changes"가 나올 때까지 코드를 맞춰가세요terminal

ℹ️ Terraform 1.5+

Terraform 1.5부터 import 블록을 코드 안에 선언할 수 있습니다. 1.6부터는 terraform plan이 자동으로 import 코드를 생성해 주는 기능이 추가됐습니다.

Part

변수 · 출력 · 모듈

variable — 환경별 값 분리

# variables.tf
variable "environment" {
  type        = string
  description = "배포 환경 (dev, staging, prod)"
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment는 dev, staging, prod 중 하나여야 합니다."
  }
}

variable "db_instance_class" {
  type    = string
  default = "db.t3.micro"
}

variable "db_password" {
  type      = string
  sensitive = true   # plan/apply 출력에서 마스킹
}variables.tf

validation 블록

Terraform 0.13부터 validation 블록으로 변수 값을 검증할 수 있습니다. 잘못된 환경 이름이 들어오면 apply 전에 에러를 발생시켜 사고를 예방합니다.

tfvars — 환경별 값 파일

# dev.tfvars
environment       = "dev"
db_instance_class = "db.t3.micro"

# prod.tfvars
environment       = "prod"
db_instance_class = "db.r6g.large"*.tfvars

$ terraform apply -var-file="dev.tfvars"
$ terraform apply -var-file="prod.tfvars"terminal

.gitignore 필수 등록

*.tfvars 파일에 비밀번호 같은 값이 들어갈 수 있으므로, 반드시 .gitignore에 추가하세요.

output — 생성된 리소스 정보 노출

output "db_endpoint" {
  value       = aws_db_instance.main.endpoint
  description = "애플리케이션에서 사용할 DB 엔드포인트"
}

output "db_password" {
  value     = aws_db_instance.main.password
  sensitive = true   # 화면 출력 시 "sensitive" 표시
}outputs.tf

sensitive = true로 설정해도 state 파일에는 평문으로 저장됩니다. state 파일 자체를 암호화(S3 encrypt)하고 접근 권한을 제한하는 것이 중요합니다.

module — 재사용 단위

project/
├── main.tf
├── variables.tf
└── modules/
    └── web-server/
        ├── main.tf        # 실제 리소스 정의
        ├── variables.tf   # 입력 변수
        └── outputs.tf     # 출력 값디렉터리 구조

# project/main.tf
module "web_dev" {
  source        = "./modules/web-server"
  environment   = "dev"
  instance_type = "t3.micro"
}

module "web_prod" {
  source        = "./modules/web-server"
  environment   = "prod"
  instance_type = "t3.large"
}main.tf

⚠️ 모듈화 함정

처음부터 모든 것을 모듈로 쪼개면 안 됩니다. 같은 패턴이 2~3번 반복될 때 모듈로 분리하는 것이 안전합니다. 너무 이른 모듈화는 변수가 수십 개로 늘어나고 디버깅이 어려워집니다.

locals — 중간 계산 값 정의

반복 사용되는 표현식을 locals로 정의하면 코드가 훨씬 깔끔해집니다.

locals {
  common_tags = {
    Environment = var.environment
    ManagedBy   = "terraform"
    Project     = "my-app"
  }
  name_prefix = "${var.environment}-myapp"
}

resource "aws_instance" "web" {
  ami           = "ami-0abc12345"
  instance_type = "t3.medium"
  tags          = local.common_tags  # 재사용
}locals 활용

for_each / count — 여러 리소스를 한 번에

# count: 숫자로 반복
resource "aws_instance" "web" {
  count         = 3
  ami           = "ami-0abc12345"
  instance_type = "t3.micro"
  tags = { Name = "web-${count.index}" }
}

# for_each: 맵/셋으로 반복 (더 권장됨)
resource "aws_s3_bucket" "buckets" {
  for_each = toset(["logs", "assets", "backups"])
  bucket   = "my-app-${each.key}"
}for_each vs count

for_each를 권장하는 이유

count는 중간 항목을 삭제하면 인덱스가 바뀌어 이후 리소스가 줄줄이 재생성됩니다. for_each는 키 기반이라 다른 항목에 영향을 주지 않습니다.

Part 6

절대로 코드에 넣으면 안 되는 것들

코드에 절대 넣지 말 것

AWS Access Key / Secret Key · RDS 비밀번호 · API Token · Private Key (.pem, .key) · JWT Secret · OAuth Client Secret · DB 접속 문자열 (계정 포함) · 개인정보

가장 흔한 실수 — Provider에 키를 직접 입력

# ❌ 절대 이렇게 하면 안 됨
provider "aws" {
  region     = "ap-northeast-2"
  access_key = "AKIAIOSFODNN7EXAMPLE"   #  
  secret_key = "wJalrXUtnFEMI/K7MDENGbPxRfiCYEXAMPLEKEY"  #  
}절대 금지

GitHub public 저장소에 push하면 자동 스캐너가 수초 내에 키를 감지합니다. AWS 계정 탈취로 수백만 원의 요금 청구가 발생한 실제 사례가 많습니다.

안전한 자격 증명 방법

방식	설명	추천 상황
환경 변수	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	로컬 개발
자격 증명 파일	`~/.aws/credentials` (aws configure)	로컬 개발
IAM Role	EC2/EKS에 Role 부여	서버에서 실행 시
AWS SSO	임시 자격 증명 사용	기업 환경
OIDC (GitHub Actions)	키 없이 임시 토큰 발급	CI/CD 파이프라인

# ✅ 올바른 방법 — Provider에 키를 적지 않음
provider "aws" {
  region = "ap-northeast-2"
  # 자격 증명은 환경 변수나 ~/.aws/credentials에서 자동으로 읽힘
}main.tf

민감 값 주입 방법

# 방법 1: 환경 변수로 주입 (로컬 작업 시)
$ export TF_VAR_db_password="MySecurePassword!"
$ terraform apply

# 방법 2: AWS Secrets Manager에서 동적으로 읽기 (운영 환경 권장)
data "aws_secretsmanager_secret_version" "db_pass" {
  secret_id = "prod/myapp/db_password"
}

resource "aws_db_instance" "main" {
  username = "admin"
  password = data.aws_secretsmanager_secret_version.db_pass.secret_string
}민감 값 주입

.gitignore 필수 항목

# .gitignore
.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfvars.json
crash.log
override.tf
override.tf.json
.terraform.lock.hcl    # 팀에 따라 커밋 여부 결정.gitignore

Part 7

변경 요청 6단계 워크플로우

요구사항을 코드로 표현 가능한 형태인지 확인

"이번에만 임시로 콘솔에서 열어주세요"도 Terraform 코드로 처리해야 합니다. 임시라도 콘솔 변경은 Drift를 만듭니다.

적용 환경 확정 (dev → staging → prod 순서)

prod에 바로 적용하지 않습니다. dev에서 먼저 검증하세요.

terraform plan 결과 검토

Add / Change / Destroy 수치가 의도와 일치하는지, Force Replacement가 있는지 확인합니다.

삭제 항목이 의도된 것인지 재확인

resource 이름 변경, 블록 삭제 등으로 의도치 않은 destroy가 발생할 수 있습니다. 이름 변경이 필요하면 terraform state mv를 먼저 실행하세요.

동료 리뷰 (코드 + plan 결과 함께)

plan 결과를 PR에 붙여넣고, 보안 / 가독성 / 영향 범위를 함께 확인합니다.

apply 후 실제 리소스 확인

apply 직후 콘솔 또는 CLI로 리소스가 정상 생성됐는지, 서비스가 정상 응답하는지, 다시 plan했을 때 "No changes"가 뜨는지 확인합니다.

# plan 결과를 파일로 저장해서 동일한 내용을 apply
$ terraform plan -out=tfplan
$ terraform apply tfplan   # 검토한 그대로만 반영됨terminal

Part 8

Plan 결과 직접 분석해보기

$ terraform plan

Terraform will perform the following actions:

  # aws_security_group.web will be updated in-place
  ~ resource "aws_security_group" "web" {
      ~ ingress = [
          - {
              - cidr_blocks = ["10.0.0.0/16"]   # 내부 IP만 허용
              - from_port   = 22
              - protocol    = "tcp"
              - to_port     = 22
            },
          + {
              + cidr_blocks = ["0.0.0.0/0"]     # 전체 인터넷 허용!
              + from_port   = 22
              + protocol    = "tcp"
              + to_port     = 22
            },
        ]
    }

  # aws_db_instance.main must be replaced
  -/+ resource "aws_db_instance" "main" {
      ~ db_name = "appdb" → "app_db"  # forces replacement
      ~ id      = "db-abc123" → (known after apply)
    }

Plan: 1 to add, 1 to change, 1 to destroy.plan 결과

분석 결과

질문	답변
변경되는 리소스는?	security group(수정) + db_instance(삭제 후 재생성) = 총 2개
SG 변경 내용	SSH 허용 IP가 내부 VPC(`10.0.0.0/16`)에서 전체 인터넷(0.0.0.0/0)으로 변경
SG 변경이 안전한가?	위험! SSH 포트를 전 세계에 여는 건 심각한 보안 취약점
RDS 처리	`db_name` 변경은 삭제 후 재생성을 유발 (Force Replacement)
데이터 영향	데이터 손실! 기존 DB 데이터가 함께 삭제됨
안전한 진행 방법	① RDS 스냅샷 백업 먼저 ② SG 변경 의도 재확인 ③ db_name 변경 방법 재검토 (마이그레이션 방안 필요)

이 plan은 apply하면 안 됩니다

SSH를 전 세계에 열고 + DB 데이터가 삭제됩니다. 즉시 코드 작성자에게 의도를 확인하고, RDS는 스냅샷 + 데이터 마이그레이션 계획을 먼저 수립해야 합니다.

Part 9 — 추가 학습

추가로 알아야 할 개념들

data source — 기존 리소스 참조

Terraform이 만들지 않은 기존 리소스(다른 팀이 만든 VPC 등)를 코드에서 참조할 때 씁니다.

# 기존에 존재하는 VPC를 참조 (만드는 게 아님)
data "aws_vpc" "existing" {
  filter {
    name   = "tag:Name"
    values = ["prod-vpc"]
  }
}

resource "aws_subnet" "new" {
  vpc_id     = data.aws_vpc.existing.id  # 참조!
  cidr_block = "10.0.100.0/24"
}data source

depends_on — 명시적 의존성

Terraform은 리소스 간 참조를 분석해서 자동으로 순서를 결정합니다. 하지만 참조 관계가 없는데도 순서가 필요할 때는 depends_on을 명시합니다.

resource "aws_iam_role_policy_attachment" "attach" {
  role       = aws_iam_role.example.name
  policy_arn = aws_iam_policy.example.arn

  depends_on = [aws_iam_role.example]  # 명시적 의존성
}depends_on

lifecycle — 리소스 생명주기 제어

resource "aws_instance" "web" {
  ami           = "ami-0abc12345"
  instance_type = "t3.medium"

  lifecycle {
    create_before_destroy = true   # 삭제 전 새 것을 먼저 만듦 (무중단)
    prevent_destroy       = true   # 실수로 destroy 막기 (prod DB에 유용)
    ignore_changes        = [ami]  # AMI 변경은 Terraform이 무시
  }
}lifecycle 블록

✅ 실무 팁

프로덕션 RDS나 중요 S3 버킷에는 prevent_destroy = true를 반드시 붙이세요. 실수로 terraform destroy를 실행해도 에러가 나면서 막아줍니다.

dynamic 블록 — 반복 속성

variable "ingress_rules" {
  default = [
    { port = 80,  cidr = "0.0.0.0/0" },
    { port = 443, cidr = "0.0.0.0/0" },
  ]
}

resource "aws_security_group" "web" {
  name = "web-sg"

  dynamic "ingress" {
    for_each = var.ingress_rules
    content {
      from_port   = ingress.value.port
      to_port     = ingress.value.port
      protocol    = "tcp"
      cidr_blocks = [ingress.value.cidr]
    }
  }
}dynamic 블록

terraform.lock.hcl — Provider 버전 고정

terraform init 후 생성되는 파일입니다. Provider의 정확한 버전과 체크섬을 기록해서 팀원 모두가 동일한 버전을 사용하도록 보장합니다. 반드시 Git에 커밋하세요.

moved 블록 — 리소스 이름 변경 시

# Terraform 1.1+ — state mv 없이 코드로 이름 변경
moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}moved 블록

이전에는 terraform state mv CLI를 써야 했지만, moved 블록으로 코드에서 선언적으로 처리할 수 있습니다.

workspaces — 하나의 코드로 여러 환경

$ terraform workspace new dev
$ terraform workspace new prod
$ terraform workspace select prod
$ terraform apply    # prod workspace에 반영workspaces

⚠️ workspace 주의사항

workspace는 state만 분리합니다. 코드는 공유되므로 환경별로 큰 차이가 있는 경우에는 디렉터리를 분리하는 방식(envs/dev, envs/prod)을 더 권장합니다.

Part 10

실무 도구 생태계

역할	도구	특징
코드 작성	Terraform / OpenTofu	OpenTofu는 완전 오픈소스 포크 (Linux Foundation)
코드 검사	tflint	문법 오류, 잘못된 인스턴스 타입 탐지
보안 검사	tfsec / Checkov	공개 S3, 평문 시크릿 등 보안 취약점 탐지
비용 예측	Infracost	plan 결과로 월 예상 비용 계산
실행 자동화	Atlantis	오픈소스, GitHub/GitLab PR에서 plan/apply 자동화
실행 자동화	Terraform Cloud (HCP)	HashiCorp SaaS, 팀 플랜 이상에서 유용
모듈 반복 제거	Terragrunt	backend 설정, variable 주입 반복 감소
State 저장	S3 + DynamoDB	AWS 환경에서 가장 흔한 조합

실무 자동화 파이프라인

.tf 코드 수정 후 PR 생성

개발자가 로컬에서 작업 후 GitHub/GitLab에 PR을 올립니다.

CI에서 자동으로 terraform plan 실행

tflint, tfsec 검사도 함께 실행합니다.

plan 결과를 PR 댓글로 게시

Atlantis 또는 GitHub Actions이 자동으로 붙입니다.

동료가 plan 결과 리뷰 후 승인

PR 머지 시 자동으로 terraform apply

개발자가 로컬에서 직접 apply를 실행하지 않습니다.

결과를 Slack 등 알림 채널에 게시

Part 11

정리 & 체크리스트

핵심 키워드 한 눈에

Provider

외부 서비스와 연결하는 플러그인

Resource

만들고 관리할 대상 (EC2, RDS, S3 …)

State

코드↔실제 인프라 매핑 기록

Plan

변경 계획 미리 보기

Apply

실제 반영

Backend

state 저장 방식 (S3 등)

Module

재사용 단위

Variable

환경별 값을 주입하는 입력

Output

생성된 리소스 정보 노출

Drift

코드↔실제 인프라 불일치 상태

locals

중간 계산 값 재사용

data

기존 리소스 참조 (읽기 전용)

실무 적용 체크리스트

☐ terraform.tfstate를 Git에 커밋하지 않는다
☐ Secret을 코드에 직접 적지 않는다
☐ 변경 전 항상 terraform plan을 확인한다
☐ Destroy 항목이 의도된 것인지 점검한다
☐ Remote Backend를 사용한다 (협업 시 필수)
☐ 콘솔에서 수동 변경을 하지 않는다 (Drift 방지)
☐ 동료 리뷰 후 apply한다
☐ Provider 버전을 고정하고 .terraform.lock.hcl을 커밋한다
☐ 중요 리소스에 prevent_destroy = true를 붙인다
☐ 모든 리소스에 ManagedBy = "terraform" 태그를 붙인다

다음 학습 방향

영역	학습 주제
Terraform 심화	`dynamic` 블록, `for_each`, `count`, `locals`, `moved` 블록
State 운영	`terraform import`, `state mv`, `state rm`, `state pull/push`
모듈 설계	Terraform Registry 공개 모듈 분석, 모듈 버전 관리
보안 강화	AWS Secrets Manager 연동, IRSA, OIDC (키 없는 CI/CD)
자동화	Atlantis, GitHub Actions, Terragrunt
분석 도구	tflint, tfsec, Checkov, Infracost
멀티 클라우드	GCP, Azure Provider
Kubernetes 연동	Helm Provider, Kubernetes Provider

마무리 한 줄 요약

코드는 Git에, 실행은 자동화에, State는 안전한 Backend에.
이 세 가지를 지키면 인프라 관리의 90%는 해결됩니다.

로깅(Observability) 완전 정리장애가 나면 어디부터 봐야 할까?

0321ljh — Fri, 15 May 2026 11:31:53 +0900

Backend · Observability · Logging

로깅(Observability) 완전 정리
장애가 나면 어디부터 봐야 할까?

운영 환경에서는 디버거를 붙일 수 없습니다. 결국 우리에게 남는 건 로그, 메트릭, 트레이스입니다. 왜 로깅이 필요한지, 언제 무엇을 봐야 하는지, 실무에서 어떻게 써야 하는지를 백엔드 개발자 관점에서 한 번에 정리합니다.

#Observability#Logging#Metrics#TraceId#SpringBoot#MSA

Section 01

왜 Observability가 필요한가

금요일 오후 6시, 퇴근 직전 슬랙에 메시지가 옵니다.

고객센터에서 결제가 안 된다고 문의가 들어왔어요. 확인 부탁드려요.

이때 무작정 코드를 뒤지는 것부터 시작하면 시간이 오래 걸립니다. 운영 환경에서는 브레이크포인트를 걸고 한 줄씩 따라갈 수 없기 때문입니다. 대신 우리는 시스템이 남긴 흔적을 따라가야 합니다.

LOGS

무슨 일이 있었는가

에러 메시지, 주문 번호, 사용자 ID, 처리 시간처럼 사건의 맥락을 보여줍니다.

METRICS

지금 이상한가

에러율, 응답시간, 트래픽, CPU처럼 숫자로 장애 징후를 빠르게 감지합니다.

TRACES

어디서 느렸는가

한 요청이 어떤 서비스와 구간을 지나며 어디서 병목이 났는지 보여줍니다.

결국 Observability의 핵심은 단순합니다. 어디까지 성공했고, 어디서 실패했는지 빠르게 좁히는 것입니다.

Section 02

Monitoring vs Observability

면접에서도 자주 나오는 질문이죠. 많은 분들이 둘을 비슷하게 생각하지만, 실무에서는 분명한 차이가 있습니다.

구분	Monitoring	Observability
핵심 질문	지금 문제가 있는가?	왜 문제가 생겼는가?
주요 데이터	메트릭, 알람	메트릭, 로그, 트레이스
대표 예시	에러율 5% 초과 알람	PG timeout이 어디서 났는지 추적
목적	감지	원인 분석

Monitoring

자동차 계기판의 경고등과 비슷합니다. "문제가 있다"는 사실은 알려주지만, 왜 생겼는지는 알려주지 못합니다.

Observability

정비사가 엔진, 팬, 오일 상태를 보며 원인을 좁혀가는 과정과 비슷합니다. 문제의 내부 상태를 이해할 수 있게 해주는 능력입니다.

Section 03

Metrics / Logs / Traces는 언제 써야 할까?

실무에서는 세 가지를 경쟁 관계로 보지 않습니다. 각자 답하는 질문이 다르기 때문에 함께 써야 합니다.

도구	한마디로	답하는 질문	언제 가장 유용한가
Metrics	숫자	얼마나 느린가? 얼마나 실패하는가?	장애 징후를 가장 먼저 볼 때
Logs	사건 기록	그 순간 무슨 일이 있었나?	실패 요청의 맥락과 에러 원인을 확인할 때
Traces	요청 경로	어느 구간에서 오래 걸렸나?	MSA, 외부 API 호출, 병목 구간 분석 시

Metrics를 볼 때

에러율이 갑자기 튀었는지 보고 싶을 때
응답시간이 평소보다 느려졌는지 확인할 때
CPU, 메모리, DB 커넥션이 포화 상태인지 볼 때

Logs를 볼 때

어떤 주문, 어떤 사용자에서 실패했는지 확인할 때
실제 에러 메시지와 에러 코드를 보고 싶을 때
스택 트레이스로 코드 레벨 원인을 좁힐 때

Traces를 볼 때

Order → Payment → PG 중 어디가 느린지 알고 싶을 때
MSA에서 서비스 간 호출 흐름을 한눈에 보고 싶을 때
외부 API, Kafka, 비동기 구간 병목을 분석할 때

장애 분석은 위에서 아래로 내려갑니다

Metrics로 이상 징후 감지 → Trace로 느린 구간 확인 → Logs로 정확한 원인 분석

평균보다 p95, p99를 보는 이유

평균 응답시간은 종종 거짓말을 합니다. 95명은 200ms에 응답받고, 5명은 10초를 기다려도 평균은 "그럭저럭"처럼 보일 수 있습니다. 그래서 실무에서는 p95, p99 같은 백분위수를 더 중요하게 봅니다.

지표	의미	실무 해석
p50	50% 사용자가 이 안에 응답받음	보통 사용자 경험
p95	95% 사용자가 이 안에 응답받음	느린 사용자 5%의 경계
p99	99% 사용자가 이 안에 응답받음	최악에 가까운 사용자 경험

Section 04

좋은 로그는 어떻게 남겨야 할까?

로그는 많이 찍는 게 핵심이 아닙니다. 검색 가능하게, 맥락 있게, 원인을 좁힐 수 있게 남겨야 합니다.

❌ 나쁜 로그

try {
  payment.process(order);
} catch (Exception e) {
  log.error("결제 실패");
}

어떤 주문인지 모릅니다
어떤 사용자인지 모릅니다
왜 실패했는지 모릅니다
얼마나 걸렸는지 모릅니다

✅ 좋은 로그

try {
  payment.process(order);
} catch (PaymentException e) {
  log.error(
    "Payment failed. orderId={}, userId={}, errorCode={}, elapsedMs={}",
    order.getId(), order.getUserId(),
    e.getErrorCode(), elapsed, e
  );
}

업무 맥락(orderId, userId)이 있습니다
원인 분류(errorCode)가 가능합니다
성능 분석(elapsedMs)이 가능합니다

구조화 로그를 쓰면 더 좋아집니다

{
  "level": "ERROR", "service": "payment-service",
  "traceId": "trc-20260515-001", "orderId": "ORD-1004",
  "userId": "U-77", "message": "External payment API timeout",
  "elapsedMs": 3200, "errorCode": "PG_TIMEOUT"
}

좋은 로그의 5가지 조건

조건	왜 필요한가	예시 필드
식별 가능	검색해서 원하는 요청을 찾아야 함	traceId, requestId
맥락 보유	어떤 업무에서 발생했는지 알아야 함	userId, orderId
출처 명확	어느 서비스의 문제인지 알아야 함	serviceName
원인 분류	알람/통계/패턴 분석에 필요	errorCode
시간 측정	느린 요청과 성능 저하를 잡아야 함	elapsedMs

로그 레벨 구분

레벨	언제 쓰는가	예시
ERROR	사용자 요청이 실제로 실패했을 때	결제 실패, DB 연결 실패
WARN	실패는 아니지만 비정상 패턴일 때	재시도 후 성공, 임계치 근접
INFO	중요한 비즈니스 이벤트를 남길 때	주문 생성, 결제 완료
DEBUG	개발/테스트 환경에서 내부 흐름을 볼 때	변수 값, 상세 분기 로직

Section 05

장애가 났을 때 어디부터 봐야 할까?

실무에서 가장 중요한 건 순서입니다. 요청 흐름을 따라 어디까지 성공했는지 확인해야 합니다.

요청이 들어왔는지 확인

access log, API Gateway, Load Balancer 로그를 봅니다.

규모 파악

Metrics에서 에러율, p95 응답시간, 특정 인스턴스/API 문제인지 먼저 봅니다.

문제 요청 식별

traceId, requestId, orderId, userId 중 하나를 확보합니다.

흐름 따라 좁히기

Controller → Service → DB → 외부 API → 응답 순서대로 확인합니다.

MSA라면 서비스 간 로그 연결

traceId로 order-service, payment-service 로그를 한 화면에서 이어 봅니다.

원인 후보 정리

코드, DB, 외부 API, 네트워크, 메시징, 리소스 포화 중 원인을 확정합니다.

결제 실패 시나리오 예시

[14:23:01] POST /orders 수신
[14:23:01] order-service:   주문 생성 시작 (orderId=ORD-1004)
[14:23:01] order-service:   주문 저장 성공 (120ms)
[14:23:04] payment-service: 외부 PG API 호출 시작
[14:23:07] payment-service: PG_TIMEOUT (3,200ms)
[14:23:07] order-service:   결제 실패 응답

주문 저장은 성공했고, 결제 서비스 호출도 성공했지만, 외부 PG API에서 3.2초 지연 후 timeout이 발생했습니다. 이 장애의 핵심 원인은 외부 결제사 응답 지연입니다.

Section 06

MSA에서 Trace ID가 왜 중요한가?

모놀리식에서는 한 서버의 로그만 보면 됐지만, MSA에서는 같은 요청의 로그가 여러 서비스에 흩어집니다.

모놀리식

Client → Backend → DB

로그가 한곳에 모여 있어 비교적 추적이 쉽습니다.

MSA

Client → Order → Payment → Coupon → Notification

같은 요청의 로그가 서비스별로 분산되어 공통 식별자가 필수입니다.

이때 필요한 것이 Trace ID입니다. 사용자 요청 하나가 시작될 때 고유 ID를 만들고, 그 요청이 거치는 모든 서비스 로그에 같은 값을 남깁니다.

order-service        | traceId=trc-001 | 주문 생성
payment-service      | traceId=trc-001 | 결제 실패
coupon-service       | traceId=trc-001 | 쿠폰 사용
notification-service | traceId=trc-001 | 알림 발송 실패

같은 요청이라면, 다음 서비스 호출 시에도 같은 traceId를 헤더에 실어 보내야 합니다.

표준 관점에서는 W3C Trace Context의 traceparent 헤더를 많이 사용합니다. 표준을 따르면 도구 간 연동이 쉬워집니다.

Section 07

Spring Boot에서 MDC로 traceId 자동 부착하기

매번 로그를 찍을 때마다 traceId를 직접 넘기면 코드가 지저분해집니다. 이때 사용하는 것이 MDC (Mapped Diagnostic Context)입니다.

왜 쓰나

요청 단위 공통 값 자동 출력

traceId, requestId 등을 스레드 컨텍스트에 넣어두고 로그 패턴에서 자동으로 출력합니다.

언제 쓰나

MSA 로그 연결이 필요할 때

Spring Boot API 서버에서 요청 단위 추적이 필요할 때 매우 유용합니다.

// 1. 요청 입구에서 traceId 생성 또는 이어받기
MDC.put("traceId", UUID.randomUUID().toString());

// 2. 이후 로그에는 자동으로 traceId 부착
log.info("Order created. orderId={}", order.getId());

// 3. 요청 종료 시 반드시 정리
MDC.clear();

Filter에서 처리하는 예시

@Component
public class TraceIdFilter extends OncePerRequestFilter {
    private static final String TRACE_HEADER = "X-Trace-Id";

    @Override
    protected void doFilterInternal(
        HttpServletRequest req, HttpServletResponse res, FilterChain chain
    ) throws ServletException, IOException {
        try {
            String traceId = req.getHeader(TRACE_HEADER);
            if (traceId == null || traceId.isBlank()) {
                traceId = UUID.randomUUID().toString();
            }
            MDC.put("traceId", traceId);
            res.setHeader(TRACE_HEADER, traceId);
            chain.doFilter(req, res);
        } finally {
            MDC.clear();
        }
    }
}

⚠️ 주의: 비동기 작업에서는 MDC가 자동 전파되지 않을 수 있습니다. @Async, CompletableFuture, Kafka Consumer 같은 구간에서는 traceId 전파 전략을 별도로 고려해야 합니다.

traceId만으로 부족할 때: Span

Trace ID: trc-001
├─ 주문 조회          20ms
├─ 쿠폰 검증          80ms
├─ 결제 요청        3200ms  ← 병목
│  ├─ 카드사 통신   3150ms
│  └─ 결과 저장       30ms
└─ 알림 발송          90ms

Kafka도 관찰 대상입니다

메시지 발행 시 traceId를 헤더에 담아 전파
Consumer 로그에도 같은 traceId 기록
lag 증가, 재처리 횟수, DLQ 적재량도 함께 모니터링

Section 08

절대 로그에 남기면 안 되는 정보

특히 개인정보와 인증 정보는 절대 평문으로 남기면 안 됩니다.

절대 금지

비밀번호
주민등록번호
카드번호 전체 / CVC / CVV
JWT, Access Token, Refresh Token
세션 ID
계좌번호, 의료 정보

흔한 실수

log.info("Request received: {}", requestDto); // ← 절대 금지

요청 객체를 통째로 찍으면 password, token, cardNumber 같은 민감 정보가 함께 남을 수 있습니다.

안전한 방식: 필요한 값만 선택적으로 기록

log.info("Payment request received. traceId={}, orderId={}, userId={}, amount={}",
    traceId, orderId, maskedUserId, order.getAmount());

마스킹 예시

// 원본: 1234-5678-9012-3456  →  결과: 1234-****-****-3456
String masked = cardNumber.substring(0, 4) + "-****-****-" + cardNumber.substring(15);

로그는 디버깅 도구이기도 하지만, 보안 관점에서는 민감한 데이터가 가장 쉽게 새는 통로가 되기도 합니다.

Section 09

실무에서는 어떤 도구를 조합할까?

중요한 건 도구 이름을 외우는 게 아니라, 각 도구가 어떤 역할을 맡는지 이해하는 것입니다.

영역	대표 도구	역할
계측 표준	OpenTelemetry	로그, 메트릭, 트레이스를 표준 방식으로 생성/전달
메트릭 저장소	Prometheus	시계열 지표 저장
로그 저장소	Loki, ELK	로그 검색/집계/분석
트레이스 저장소	Jaeger, Zipkin, Tempo	분산 추적 및 병목 확인
시각화	Grafana, Kibana	대시보드, 검색, 알람
에러 트래킹	Sentry	에러 그룹화, 스택 추적, 영향 범위 확인
클라우드 기본 도구	CloudWatch, Azure Monitor	기본 로그/메트릭/알람 운영

회사 규모별로 자주 보이는 조합

초기 스타트업Sentry + CloudWatch 또는 Datadog

중간 규모 회사Sentry + 통합 SaaS (Datadog, New Relic)

Kubernetes 기반Prometheus + Grafana + Loki + Tempo

한국 대기업/금융권Pinpoint + 자체 로그 시스템

Section 10

실무 체크리스트

운영 환경에서 바로 써먹을 수 있는 기준만 짧게 정리합니다.

로그 체크리스트

traceId / requestId가 있는가
userId / orderId 같은 업무 맥락이 있는가
serviceName, errorCode가 있는가
elapsedMs를 남기고 있는가
Exception 객체를 마지막 인자로 넘기고 있는가
민감 정보를 마스킹하거나 제외했는가

장애 대응 체크리스트

요청이 실제로 들어왔는지 먼저 확인
Metrics로 범위와 규모를 파악
문제 요청 하나를 선정
traceId로 관련 로그 연결
어디까지 성공했는지 순서대로 확인
DB / 외부 API / 네트워크 / 코드 중 원인 확정

좋은 Observability의 목표는 로그를 예쁘게 쌓는 것이 아니라, 새벽 2시에도 원인을 빠르게 좁힐 수 있게 만드는 것입니다.

마무리

운영 환경에서 로그는 단순한 출력문이 아닙니다. 메트릭은 문제가 있다고 알려주고, 트레이스는 어디가 느린지 보여주며, 로그는 정확히 무슨 일이 있었는지 말해줍니다.

백엔드 개발자가 성장할수록 중요한 건 기능 구현 속도만이 아닙니다. 문제가 생겼을 때 빠르게 복구할 수 있는 시스템을 만드는 능력, 그게 바로 Observability입니다.

#로그는많이가아니라찾기쉽게 #Metrics먼저Trace다음Logs마지막 #MSA에서는TraceId필수 #민감정보는절대로그금지

OpenFeign 공식 문서 ,선언적 HTTP 클라이언트의 모든 것

0321ljh — Fri, 15 May 2026 11:20:43 +0900

[Spring Cloud] OpenFeign 공식 문서 파헤치기: 선언적 HTTP 클라이언트의 모든 것

MSA(Microservices Architecture) 구조에서 서비스 간 통신(Inter-service Communication)은 피할 수 없는 과제입니다. 오늘은 이를 가장 자바답고 우아하게 해결하는 Spring Cloud OpenFeign의 핵심 개념과 실무 적용 팁을 정리해 보겠습니다.

1. OpenFeign이란?

Feign은 선언적 HTTP 클라이언트(Declarative HTTP Client)입니다. 인터페이스를 작성하고 어노테이션을 붙이는 것만으로도 실제 HTTP 요청을 수행하는 구현체를 스프링이 자동으로 만들어줍니다. 개발자는 로직에만 집중할 수 있게 됩니다.

2. 시작하기 및 속성 해상도(Attribute Resolution)

의존성 추가 후 @EnableFeignClients를 선언하면 준비완료

@SpringBootApplication
@EnableFeignClients
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

알아두어야 할 개념: 즉시 해석(Eager Resolution)

최근 버전부터는 @FeignClient의 속성값을 빌드 시점(AOT)에 미리 해석하는 것이 기본값이 되었습니다.
이는 애플리케이션 시작 속도를 높이고 메모리를 절약하기 위함입니다. 만약 과거처럼 런타임에 지연 해석(Lazy)이 필요하다면 별도의 설정이 필요합니다.

3. Named Client: 독립된 설정의 핵심

Feign의 가장 중요한 설계 철학 중 하나는 Named Client입니다. 각 Feign 클라이언트는 자신만의 별도 ApplicationContext를 가집니다.

개별 설정: 'A 서비스'는 타임아웃 2초, 'B 서비스'는 타임아웃 5초와 같은 독립적 설정이 가능합니다.
컴포넌트 구성: Encoder, Decoder, Logger, Contract 등을 클라이언트마다 다르게 갈아 끼울 수 있습니다.

4. 실무 적용 시 필수 체크 포인트

① 타임아웃(Timeout) 설정

네트워크 지연이나 외부 서비스 장애가 내 서비스로 전파되는 것을 막는 첫 번째 방어선입니다.

ConnectTimeout: 서버와 연결을 맺는 시간 제한
ReadTimeout: 연결 후 응답 데이터가 오기까지의 시간 제한

② ErrorDecoder: 예외 처리의 정석

Fallback이 단순히 '에러 발생 시 기본값'을 주는 것이라면, ErrorDecoder는 HTTP 상태 코드(4xx, 5xx)에 따라 비즈니스 예외를 던질 수 있게 해줍니다.

"404가 오면 EntityNotFoundException을 던지고, 401이 오면 로그아웃 처리를 하겠다"는 식의 정교한 제어가 가능합니다.

③ 로깅(Logging) 레벨

Feign 로깅은 오직 DEBUG 레벨에서만 작동합니다. 성능과 보안(헤더의 민감 정보 노출 방지) 때문입니다.

NONE, BASIC, HEADERS, FULL 네 가지 단계로 제어할 수 있습니다.

5. 장애 탄력성: Circuit Breaker & Fallback

분산 환경에서는 특정 서비스가 죽었을 때 시스템 전체가 마비되지 않도록 하는 것이 중요합니다.

@FeignClient(name = "product-service", fallback = ProductFallback.class)
public interface ProductClient { ... }

@Component
class ProductFallback implements ProductClient {
    @Override
    public String getProductInfo() {
        return "정보를 일시적으로 불러올 수 없습니다.";
    }
}

FallbackFactory를 사용하면 어떤 에러(Throwable) 때문에 폴백이 발생했는지 원인 로그를 남길 수 있어 유지보수에 유리합니다.

6. 한 단계 더 나아가는 성능 최적화 팁

HTTP 커넥션 풀(Connection Pool) 사용

Feign은 기본적으로 JDK의 HttpURLConnection을 사용합니다. 이는 매 요청마다 새로운 연결을 맺기 때문에 성능이 떨어집니다. 실무에서는 반드시 Apache HttpClient나 OkHttp를 사용하여 커넥션을 재사용하도록 설정하세요.

Gzip 압축

요청/응답 데이터 양이 많다면 spring.cloud.openfeign.compression 설정을 통해 네트워크 비용을 줄일 수 있습니다.

7. 요약: 언제 무엇을 써야 할까?

상황	추천 도구
일반적인 Spring MVC 기반의 동기 통신	OpenFeign
대규모 트래픽 처리를 위한 비동기 통신	WebClient
단순하고 짧은 일회성 HTTP 호출	RestTemplate (유지 관리 모드)

OpenFeign은 설정이 간편하지만, 그 내부 동작 원리(Named Context, ErrorDecoder 등)를 이해하고 써야 예상치 못한 장애에 대응할 수 있습니다.

MSA 분산 환경의 동시성 제어와 비동기 통신 정리

0321ljh — Tue, 12 May 2026 15:37:59 +0900

TIL · Redis · MSA · Concurrency Control
Redis 분산 락, Redisson Watchdog, Pub/Sub vs MQ

오늘은 MSA 환경에서 반드시 마주치게 되는 동시성 문제를 Redis 중심으로 정리했다. 단순히 "락을 건다" 수준이 아니라, 왜 초과 판매가 발생하는지, SETNX가 왜 위험할 수 있는지, Redisson Watchdog은 언제 믿어도 되는지, Pub/Sub과 MQ는 어떻게 구분해야 하는지까지 한 번에 연결해서 정리해봤다.

한 줄 요약
분산 환경에서는 여러 서버가 동시에 같은 자원을 건드리기 때문에 단일 서버 시절의 방식만으로는 정합성을 지키기 어렵다. 그래서 Redis 분산 락, 원자적 명령어, Lua 스크립트, 메시지 큐 같은 도구를 문제 성격에 맞게 선택해야 한다.

1. 왜 MSA에서는 동시성 문제가 더 무서워질까?

단일 서버 환경에서는 하나의 프로세스 안에서 synchronized나 JVM lock으로 어느 정도 제어가 가능했다. 하지만 MSA 환경에서는 여러 서버 인스턴스가 동시에 같은 재고, 쿠폰 수량, 계좌 잔액 같은 공유 자원에 접근한다. 이때 각 서버가 "지금 재고가 있네?"라고 동시에 판단하면 초과 판매(Over-sell) 같은 문제가 발생한다.

결국 핵심은 읽기와 쓰기 사이의 틈이다. 여러 요청이 같은 값을 읽고, 그 사이에 서로의 변경을 모른 채 업데이트를 수행하면 데이터 정합성이 깨진다. 이 문제를 막기 위해 등장하는 대표적인 해법이 바로 분산 락(Distributed Lock)이다.

2. 분산 락은 무엇이고, 왜 Redis를 많이 쓸까?

분산 락은 쉽게 말해 "공용 화장실 열쇠" 같은 개념이다. 여러 서버가 공용 자원에 접근하려고 할 때, 먼저 열쇠를 가져간 서버만 임계 구역에 들어가고 나머지는 기다리거나 실패 처리하는 방식이다.

Redis는 싱글 스레드 기반으로 명령이 원자적으로 처리되고, 메모리 기반이라 매우 빠르다. 그래서 짧은 시간 동안 "오직 하나만 들어가게" 만드는 락 저장소로 자주 사용된다.

핵심 명령

SET lock:product:1 request-uuid NX EX 5

여기서 중요한 건 NX와 EX를 함께 쓰는 것이다. 예전처럼 SETNX로 먼저 락을 잡고, 다음 줄에서 EXPIRE를 따로 호출하면 그 사이 서버가 죽었을 때 락이 영원히 안 풀릴 수 있다. 즉, 락 획득과 TTL 설정은 반드시 한 번의 원자적 명령으로 처리해야 한다.

3. 문서 속 예시와 도표에서 배운 포인트

재고 차감 / 초과 판매 시나리오

여러 서버가 동시에 재고를 읽고 각각 "재고 있음"으로 판단한 뒤 차감을 수행하면 실제 수량보다 더 많이 판매되는 상황이 생긴다. 이 예시는 MSA에서 분산 락이 왜 필요한지를 가장 직관적으로 보여준다.

데드락 시나리오

락은 잡았지만 만료 시간 설정 전에 서버가 죽으면, 락 키가 영구히 남아 다른 서버가 영원히 진입하지 못한다. 그래서 SETNX와 EXPIRE를 분리 호출하는 구현은 실무에서 매우 위험하다.

동시성 제어 기술 비교표

DB 비관적 락, DB 낙관적 락, Redis 기본 락, Redisson은 각각 장단점이 다르다. 정합성이 최우선이면 DB 락이 더 맞을 수 있고, 고성능 선착순 처리에는 Redis 계열이 유리하다. 결국 기술 선택은 트래픽과 정합성 요구사항의 균형 문제다.

Pub/Sub vs MQ 비교표

Redis Pub/Sub은 빠르지만 휘발성이고, Kafka/RabbitMQ는 보관과 Ack를 통해 더 높은 처리 보장성을 제공한다. 채팅 알림처럼 실시간성이 중요한 경우와, 결제 이벤트처럼 절대 유실되면 안 되는 경우를 반드시 구분해야 한다.

4. Redisson을 쓰면 왜 편해질까?

직접 Redis 락을 구현하면 생각보다 신경 쓸 게 많다. 락 획득 재시도, TTL 관리, 락 해제 시 본인 검증, 예외 상황 처리, 스핀락 부하 문제까지 모두 개발자가 챙겨야 한다. 반면 Redisson은 이런 부분을 더 안전하고 편하게 추상화해준다.

Watchdog이 중요한 이유

비즈니스 로직이 예상보다 오래 걸리면 TTL이 먼저 끝나서 락이 풀릴 수 있다. 그러면 아직 작업 중인데도 다른 서버가 같은 자원에 들어와 버린다. Redisson의 Watchdog은 이런 상황을 막기 위해 락 만료 시간을 자동 연장해준다.

다만 함정도 있다. leaseTime을 직접 지정하면 Watchdog이 동작하지 않는다. 그래서 "무조건 leaseTime 넣는 게 더 안전하겠지?"라고 생각하면 오히려 긴 작업에서 락이 중간에 풀릴 수 있다. 이건 실무에서 정말 자주 헷갈리는 포인트다.

5. 락 해제는 왜 UUID 검증이 필요할까?

락 값(value)에 단순히 1 같은 값을 넣으면 안 된다. 내 요청이 락을 잡은 뒤 시간이 지나 TTL이 만료되고, 다른 요청이 같은 키로 새 락을 잡았다고 가정해보자. 그런데 이전 요청이 뒤늦게 DEL lock:key를 실행하면, 내가 잡은 락이 아니라 다른 요청이 새로 잡은 락을 지워버릴 수 있다.

그래서 락 value에는 반드시 UUID 같은 고유 식별자를 넣고, 해제할 때도 "현재 value가 내 UUID와 같을 때만 삭제"해야 한다. 이 검증과 삭제는 보통 Lua 스크립트로 원자적으로 처리한다.

예시 개념

if redis.call("get", KEYS[1]) == ARGV[1] then
  return redis.call("del", KEYS[1])
else
  return 0
end

6. Redis Pub/Sub과 MQ는 어떻게 구분해야 할까?

문서에서 가장 인상적이었던 비교는 Redis Pub/Sub을 "라디오 방송", Kafka를 "우체국"에 비유한 부분이다. Redis Pub/Sub은 발행 시점에 연결된 구독자에게만 메시지가 전달되고, 중간에 구독자가 내려가 있으면 메시지는 그대로 사라진다.

반면 Kafka나 RabbitMQ 같은 메시지 큐는 메시지를 저장하고, 소비자의 처리 여부를 추적할 수 있다. 그래서 이벤트 유실이 치명적인 주문, 결제, 정산, 포인트 적립 같은 기능에는 MQ가 더 적합하다. 반대로 실시간 알림, 일시적인 브로드캐스트, 워커 깨우기 같은 용도라면 Pub/Sub이 훨씬 가볍고 빠르다.

7. 락 없이 해결하는 방법도 있다

이 문서가 좋은 이유는 락만 강조하지 않는다는 점이다. 단순 수량 증가/감소라면 락보다 INCR, DECR 같은 원자적 명령이 훨씬 빠르고 단순하다. 또 여러 조건이 걸린 복합 로직도 Lua 스크립트로 묶어 서버 내부에서 원자 실행하면 네트워크 왕복을 줄이면서 안전하게 처리할 수 있다.

즉, 실무에서는 먼저 "이걸 진짜 락으로 풀어야 하나?"를 질문해야 한다. 카운터 문제인지, 상태 전이 문제인지, 메시지 전달 문제인지에 따라 정답이 달라진다.

8. 실무에서 추가로 꼭 알아야 할 포인트

Redis 분산 락은 매우 유용하지만, 완벽한 분산 합의 시스템은 아니다. 단일 마스터 복제 지연이나 장애 전환 상황에서는 상호 배제가 깨질 가능성이 있다. 그래서 금융처럼 정합성 요구 수준이 매우 높은 시스템에서는 Redis 락만 믿지 않고 DB 락이나 추가 검증 로직을 함께 사용하는 다층 방어 전략이 필요하다.

또한 락이 있어도 중복 요청은 언제든 발생할 수 있으므로 멱등성(idempotency)을 반드시 고려해야 한다. 결제 승인, 주문 생성, 쿠폰 발급 같은 기능은 같은 요청이 여러 번 들어와도 결과가 한 번만 반영되도록 설계해야 실제 운영에서 안전하다.

그리고 "Exactly-once"라는 표현은 매우 조심해서 써야 한다. 대부분의 시스템은 결국 중복 가능성을 전제로 설계하고, idempotency key, 상태 전이 검증, outbox/inbox 패턴 등으로 안정성을 확보한다.

9. 실무 사례로 이해한 선택 기준

물류나 재고 시스템에서는 DB 락만으로 버티기 어렵기 때문에 Redis 기반 분산 락이 성능상 유리할 수 있다. 하지만 금융 서비스처럼 오차가 허용되지 않는 영역에서는 Redis 락만으로 끝내지 않고 DB 레벨 검증까지 겹쳐 쓰는 방식이 더 현실적이다.

또 선착순 이벤트 시스템에서는 Pub/Sub을 "데이터 전달"이 아니라 "워커를 깨우는 트리거" 정도로만 쓰고, 실제 데이터는 Redis List나 MQ에 안전하게 적재하는 방식이 훨씬 안정적이다. 이 지점이 Pub/Sub과 MQ를 구분해서 써야 하는 이유를 가장 잘 보여준다.

10. 오늘의 TIL

오늘의 핵심 배움 1
분산 환경의 동시성 문제는 "여러 서버가 동시에 읽고 수정한다"는 사실에서 시작된다.

오늘의 핵심 배움 2
Redis 락은 빠르지만, 락 획득/TTL/해제 검증을 모두 제대로 설계해야 안전하다.

오늘의 핵심 배움 3
Redisson Watchdog은 편리하지만, leaseTime을 직접 주면 동작하지 않는다는 점을 반드시 기억해야 한다.

오늘의 핵심 배움 4
Redis Pub/Sub은 실시간 브로드캐스트에 적합하고, 유실되면 안 되는 비즈니스 이벤트는 MQ로 다뤄야 한다.

오늘의 핵심 배움 5
모든 동시성 문제를 락으로 풀 필요는 없고, 원자적 명령어와 Lua 스크립트가 더 좋은 해법일 때도 많다.

11. 면접 대비 한 줄 답변

Q. SETNX와 EXPIRE를 왜 분리하면 안 되나요?
락을 잡은 뒤 EXPIRE 전에 서버가 죽으면 락이 영원히 안 풀려 데드락이 발생할 수 있기 때문이다.

Q. Redisson Watchdog은 언제 동작하나요?
일반적으로 leaseTime을 직접 주지 않았을 때 동작하며, 락의 TTL을 자동 연장해준다.

Q. Pub/Sub과 MQ의 가장 큰 차이는 뭔가요?
Pub/Sub은 휘발성 브로드캐스트이고, MQ는 메시지 저장과 처리 보장을 제공한다.

Q. 락 없이 동시성을 제어할 수도 있나요?
가능하다. 단순 카운팅은 INCR/DECR, 복합 조건은 Lua 스크립트로 원자 처리할 수 있다.

[Backend] Redis 코어 아키텍처와 기초 특강

0321ljh — Tue, 12 May 2026 11:27:11 +0900

1초에 수만 건의 트래픽이 몰리는 대형 서비스에서 RDBMS만으로 버티는 것은 불가능에 가깝습니다.
물리적인 디스크 I/O의 한계를 극복하고 쾌적한 사용자 경험을 제공하기 위해 Redis는 이제 선택이 아닌 '생존'을 위한 필수 인프라가 되었습니다.
오늘은 실무에서 Redis를 다룰 때 반드시 챙겨야 할 핵심 아키텍처와 전략을 정리.

1. Redis가 압도적으로 빠른 물리적 이유

기존 DB가 지하 서고에 있는 책을 가지러 가는 과정이라면, Redis는 책상 바로 위 '손 닿는 곳에 둔 책꽂이'와 같습니다.

In-Memory의 위력: RAM은 전자의 이동만으로 데이터를 처리합니다.
메모리 접근 속도(약 120ns)는 아무리 빠른 SSD(약 50~150us)보다 최소 1,000배가량 빠릅니다.
싱글 스레드와 이벤트 루프: 여러 일꾼이 복잡하게 락(Lock)을 걸고 싸우는 대신, 한 명의 초인적인 웨이터(이벤트 루프 다중화)가 모든 주문을 순차적으로, 하지만 미친 듯이 빠르게 처리하여 컨텍스트 스위칭 오버헤드를 없앴습니다.

2. 실무에서 가장 많이 쓰는 캐싱 전략

① Look-Aside (Cache-Aside)

가장 대중적인 방식으로 조회가 많은 서비스에 적합합니다.
앱이 캐시를 먼저 보고, 없으면 DB에서 가져와 캐시에 채워넣습니다.
장점은 Redis 장애 시에도 DB를 통해 서비스 유지가 가능하다는 안정성에 있습니다.

② Write-Back

모든 쓰기를 Redis에 먼저 하고 주기적으로 DB에 배치(Batch) 반영합니다.

좋아요 폭주나 실시간 이벤트 등 쓰기 트래픽이 몰릴 때 DB의 부하를 막아주는 강력한 무기이지만, DB 반영 전 Redis 장애 시 데이터 유실 위험이 있음을 인지해야 한다.

⚠️ 운영 함정: 캐시 스탬피드 (Cache Stampede)

인기 상품 100개의 만료 시간을 똑같이 '정오 12시'로 설정하면 안 됩니다.
12시 정각에 캐시가 동시에 삭제되는 순간, 수만 명의 유저가 DB로 한꺼번에 몰려 서버가 다운된다
.해결책은 TTL 설정 시 1~5분 정도의 랜덤 난수(Jitter)를 더해 만료 시점을 분산해야 한다.

3. 현업 개발자가 반드시 추가로 알아야 할 운영 포인트

3.1 고가용성(HA) 구성 : Replication & Sentinel

실무에서 단일 Redis 인스턴스(Standalone)를 쓰는 것은 매우 위험합니다.
Master-Slave 복제를 통해 데이터를 실시간 백업하고, Master 서버가 죽었을 때 Sentinel이 이를 감지해 자동으로 Slave를 Master로 승격(Failover)시키는 구성이 필수이다.

3.2 메모리 정책 (Eviction Policy)

메모리는 한정된 자원입니다. 메모리가 가득 찼을 때 어떤 데이터를 지울지 결정해야 합니다.

allkeys-lru: 가장 최근에 사용되지 않은 데이터를 삭제 (가장 추천되는 정책)
volatile-ttl: 만료 시간이 설정된 키 중 수명이 가장 짧은 것부터 삭제

3.3 Big Keys & Hot Keys 피하기

싱글 스레드 특성상, 하나의 키에 너무 큰 데이터(Big Key)를 넣거나 특정 키 하나에만 트래픽이 몰리면(Hot Key) 전체 시스템이 멈춥니다.
대량의 데이터는 Hash나 여러 키로 쪼개어 저장하는 설계가 필요합니다.

Senior's Advice: 데이터 정합성 관리

DB 업데이트 시 캐시를 지울지, 아니면 새 값으로 바꿀지 고민되시나요?
실무에서는 'Active Invalidation', 즉 DB 수정 직후 캐시를 명시적으로 삭제(DEL)하는 방식을 기본으로 한다.
여기에 시스템 오류를 대비해 적절한 TTL을 이중 안전장치로 거는 것이 정석이라고 한다.

4. 마무리

단순 캐싱을 넘어 배달의민족 B마트 사례처럼 분산 락(Distributed Lock)을 통해 동시성을 제어하거나, Sorted Set을 활용한 실시간 랭킹 시스템을 구축하는 등 Redis는 활용도가 무궁무진합니다.
하지만 비싼 메모리 자원을 쓰는 만큼, 데이터의 수명(TTL)을 엄격히 관리하고 모니터링하는 습관을 가져야 한다.

참고 사이트

[Backend] 데이터 성능의 핵심, Redis 기초]

0321ljh — Mon, 11 May 2026 15:20:17 +0900

1. 인메모리 저장소는 왜 필요할까

Spring Boot 프로젝트에서 주로 사용하는 RDBMS(MySQL, PostgreSQL 등)는 영속성(Persistence)을 위해 데이터를 파일 시스템(HDD, SSD)에 저장합니다.
서비스 종료 시에도 데이터가 유지되어야 하는 핵심 정보에는 필수적이지만, 물리적인 디스크 I/O가 발생하기 때문에 속도가 상대적으로 느릴 수밖에 없습니다.

반면, 로그인 정보, 장바구니, 게시글 조회수와 같이 변경이 잦고 일시적인 데이터는 메모리(RAM)를 사용하는 데이터베이스가 훨씬 유리합니다. 메모리는 디스크보다 압도적으로 빠른 읽기/쓰기 성능을 제공하기 때문입니다.

2. Redis의 정의와 핵심 특징

Redis(Remote Dictionary Server)는 Java의 Map<Key, Value> 구조와 유사하게 데이터를 저장하는 대표적인 인메모리 NoSQL 데이터베이스입니다.

초고속 성능: RAM 기반 저장 방식으로 복잡한 입출력 과정이 생략되어 지연 시간이 극도로 낮습니다.
다양한 자료구조: 단순 String 외에도 List, Set, Hash, Sorted Set 등을 지원하여 복잡한 로직을 DB 레벨에서 처리할 수 있습니다.
NoSQL 접근법: 스키마가 엄격하지 않아 확장성과 유연성이 뛰어나며 비정형 데이터를 처리하기에 최적입니다.

⚠️ 중요: 라이선스 변경
2024년 3월 20일 이후, Redis는 라이선스를 기존 BSD에서 SSPLv1 및 RSALv2로 변경했다.
일반적인 상용 서비스 사용에는 여전히 무료이지만, Redis를 직접 재판매하는 클라우드 서비스 제공 업체 등은 제약이 생겼으니 프로젝트 도입 시 참고가 필요하다.

3. 실무자가 알아야 할 Redis 최신 트렌드 (GitHub Insight)

최신 Redis(7.x 버전 이상)와 실무 개발 환경에서 반드시 챙겨야 할 핵심 내용입니다.

3.1 데이터 지속성 (Persistence: RDB vs AOF)

Redis는 기본적으로 휘발성이지만, 데이터를 디스크에 백업하는 두 가지 메커니즘을 제공합니다.

RDB (Redis Database): 특정 시점의 메모리 스냅샷을 생성합니다. 파일 크기가 작고 복구가 빠르지만, 스냅샷 사이의 데이터 손실 위험이 있습니다.
AOF (Append Only File): 모든 쓰기 명령을 로그로 기록합니다. 데이터 유실이 거의 없지만 파일이 커지고 복구 속도가 느릴 수 있습니다.

3.2 Java 클라이언트 선택: Lettuce vs Jedis

Spring Boot 환경에서 Redis를 사용할 때 클라이언트 선택이 중요하다.
최근 GitHub 동향과 Spring Data Redis의 기본값은 Lettuce입니다.
Jedis는 동기 방식인 반면, Lettuce는 Netty 기반의 비동기/논블로킹(Non-blocking) 구조를 가져 성능과 확장성 면에서 훨씬 우수합니다.

3.3 Redis Streams & Probabilistic Data Structures

단순 캐싱을 넘어 최근에는 로그 수집이나 메시징을 위한 Redis Streams가 많이 쓰입니다. 또한 대규모 데이터에서 중복 체크를 위한 Bloom Filter와 같은 확률적 자료구조 기능을 통해 메모리 사용량을 획기적으로 줄이는 설계가 유행하고 있습니다.

4. 실전 활용 사례

활용 분야	상세 내용
Session Clustering	다중 서버 환경에서 동일한 사용자 세션 정보를 공유할 수 있도록 지원
Caching	자주 조회되는 DB 쿼리 결과를 저장하여 전반적인 응답 속도 개선
Leaderboard	Sorted Set 자료구조를 활용하여 실시간 순위 시스템 구현
Rate Limiting	특정 API에 대한 요청 횟수를 제한하는 보안 기능 구현

알아야 될 것 "Redis는 메모리는 디스크보다 훨씬 비싼 자원이기 때문에, 모든 데이터를 Redis에 넣으려는 시도는 지양해야 한다.
'데이터의 수명(TTL)'을 명확히 설정하고, 'Eviction Policy(메모리 부족 시 삭제 정책)'를 서비스 성격에 맞게 튜닝하는 것이 시역량인거 같다 .

5. 참고 사이트

JIRA MCP와 Harness Engineering

0321ljh — Fri, 8 May 2026 12:40:05 +0900

JIRA MCP와 Harness Engineering

개발자가 알아야될 필수적인 입문 지식들 특강 정리

왜 이 주제들이 한꺼번에 묶여서 나올까?

겉으로 보면 Jira는 프로젝트 관리 도구이고, MCP는 AI 연동 표준이며, Harness Engineering은 개발 문화 이야기처럼 보입니다. 하지만 이 셋은 사실 같은 질문을 다른 각도에서 다룹니다.

“AI 에이전트가 우리 팀에서 사람처럼 일하려면, 무엇이 준비되어 있어야 할까?”

이 질문에 답하려면 세 가지가 필요합니다. 첫째, AI가 팀의 업무 도구와 연결되어야 합니다. 둘째, AI가 읽고 판단할 수 있도록 프로젝트의 규칙과 맥락이 정리되어 있어야 합니다. 셋째, 코드와 배포 상태가 모두에게 보이는 구조여야 합니다.

1. Jira란 무엇인가

Jira는 Atlassian이 만든 대표적인 이슈 트래킹 및 프로젝트 관리 도구입니다.
쉽게 말하면, 팀이 해야 할 일을 쪼개서 기록하고, 누가 맡고 있고, 지금 어느 단계에 있으며, 언제 끝나야 하는지를 한곳에서 관리하는 시스템입니다.
Atlassian은 Jira를 팀이 계획하고, 추적하고, 전달하는 일을 하나의 흐름으로 연결하는 도구로 설명한다.

개발자가 처음 알아야 할 Jira 핵심 용어

용어	쉽게 설명하면
Issue	해야 할 일 하나를 담는 기본 단위. 버그, 기능 개발, 작업 요청 등이 모두 이슈가 될 수 있음
Project	관련 이슈들을 묶어 관리하는 공간
Board	이슈를 칸반처럼 시각화해서 보여주는 화면
Backlog	아직 진행 전이지만 앞으로 해야 할 일 목록
Sprint	정해진 기간 동안 완료하기로 한 작업 묶음
Workflow	To Do → In Progress → Done 같은 상태 흐름

Jira의 강점은 단순히 할 일 목록을 적는 데 있지 않습니다.

팀이 지금 어떤 일을 하고 있는지, 무엇이 막혀 있는지, 어떤 일이 먼저 처리되어야 하는지를 모두가 같은 화면에서 볼 수 있다는 점이 핵심입니다.

특히 소프트웨어 팀에서는 버그, 기능, 배포 준비, 리뷰 요청 같은 서로 다른 종류의 작업을 한 체계로 묶을 수 있다는 점이 중요합니다.

이슈 트래킹은 왜 중요한가

개발 팀은 늘 여러 일이 동시에 돌아갑니다. 버그도 처리해야 하고, 신규 기능도 만들어야 하며, 운영 이슈도 확인해야 합니다.

이때 이슈 트래킹이 없으면 팀은 “무엇이 가장 중요한가”, “누가 무엇을 맡고 있는가”, “어디서 멈췄는가”를 계속 사람 머리로 기억해야 합니다. Jira 같은 도구는 이 모든 작업을 기록하고 연결해 팀의 공용 작업 기억장치 역할을 합니다.

Jira 보드는 초보자에게 특히 유용합니다. Scrum 보드는 스프린트처럼 일정한 주기로 일하는 팀에 잘 맞고, Kanban 보드는 작업 흐름을 끊기지 않게 관리하는 팀에 잘 맞습니다.

즉, Jira는 단순한 할 일 앱이 아니라 개발 방식 자체를 시각화하는 도구라고 보는 편이 더 정확합니다.

초보자 포인트
Jira를 처음 볼 때 “왜 이렇게 복잡하지?”라고 느끼기 쉽습니다.
그런데 실제로는 반대이다 팀의 현실이 원래 복잡한데, Jira가 그 복잡함을 눈에 보이게 만든 것이다

2. MCP란 무엇인가

MCP는 Model Context Protocol의 약자입니다. 쉽게 말하면, AI가 외부 도구와 데이터를 표준 방식으로 연결하기 위한 공통 인터페이스입니다. 공식 문서는 MCP를 “AI 애플리케이션을 외부 시스템에 연결하는 오픈 표준”으로 설명하며, USB‑C처럼 하나의 규격으로 다양한 도구를 연결하는 비유를 사용합니다.

왜 이런 표준이 필요할까요? 아무리 똑똑한 AI라도, 외부 시스템과 연결되지 않으면 실제 업무를 할 수 없습니다. 예를 들어 AI가 Jira 티켓을 읽거나, GitHub PR을 열거나, 사내 문서를 검색하려면 각 시스템과 연결되는 통로가 필요합니다. Anthropic은 MCP가 이런 파편화된 통합을 줄이고, AI 시스템이 필요한 데이터에 더 단순하고 안정적으로 접근하게 만든다고 설명합니다.

MCP를 아주 쉽게 비유하면

예전에는 기기마다 충전 케이블이 달랐다면, 이제는 USB‑C 하나로 통일되는 방향으로 가고 있습니다. MCP도 비슷합니다. 도구마다 AI 연결 방식을 따로 만드는 대신, AI와 외부 시스템이 공통 규격으로 대화하게 만드는 것입니다.

공식 소개에 따르면 MCP를 쓰면 AI는 데이터 소스, 각종 도구, 워크플로우와 연결될 수 있습니다. 그래서 단순히 대답만 하는 챗봇이 아니라, 실제로 검색하고, 읽고, 실행하고, 업데이트하는 에이전트로 발전할 수 있습니다.

Anthropic은 MCP를 통해 개발자가 각 데이터 소스마다 개별 커넥터를 계속 만드는 대신, 하나의 표준 프로토콜 위에서 AI와 시스템을 연결할 수 있다고 설명합니다.
즉, MCP의 핵심은 “AI가 더 똑똑해지는 것”이 아니라, AI가 실제 업무 환경과 연결되는 것에 있습니다.

3. JIRA MCP는 무엇을 바꾸는가

Jira를 AI와 연결하는 대표적인 방식이 바로 Atlassian의 Rovo MCP Server입니다. Atlassian은 이를 Atlassian Cloud와 외부 AI 도구를 연결하는 클라우드 기반 브리지로 설명합니다. 이 구성을 사용하면 AI가 Jira, Confluence, Compass 데이터를 실시간으로 읽고 활용할 수 있습니다.

초보자 입장에서 중요한 변화는 하나입니다. 이제 AI가 Jira를 “설명받는 대상”이 아니라, 직접 상호작용하는 도구로 다룰 수 있다는 점입니다. 예전에는 사람이 Jira 화면에 들어가 필터를 만들고, 티켓을 열고, 내용을 읽고, 정리 결과를 다른 문서로 옮겨야 했습니다. 하지만 JIRA MCP가 연결되면, AI가 그 과정을 자연어 명령을 받아 대신 수행할 수 있는 기반이 생깁니다.

예를 들면 이런 흐름입니다

“내가 이번 스프린트에 맡은 티켓 정리해줘.”
“결제 관련 진행 중 버그만 모아서 요약해줘.”
“회의록 보고 액션 아이템을 Jira 이슈로 정리해줘.”

Atlassian 문서에 따르면 Rovo MCP Server는 Jira, Confluence, Compass와 연결되며, ChatGPT, Claude, GitHub Copilot CLI, Gemini 등 여러 AI 클라이언트와 연동할 수 있습니다. 중요한 점은 이 연결이 별도의 슈퍼 권한을 주는 방식이 아니라, 사용자가 이미 가진 권한 범위 안에서만 동작한다는 것입니다. 즉, 내가 볼 수 없는 이슈는 AI도 볼 수 없습니다.

이 권한 모델은 실무에서 매우 중요합니다. AI가 강력해질수록 사람들이 가장 먼저 걱정하는 것은 보안과 접근 범위인데, Rovo MCP Server는 OAuth 2.1 기반 인증과 기존 Atlassian 권한 체계를 그대로 따르는 방식으로 설계되어 있습니다. 즉, “AI가 내 권한으로 대신 일한다”는 위임 모델에 가깝습니다.

개발자 입장에서 JIRA MCP가 유용한 장면

스탠드업 전에 내 티켓 상태를 자동 정리할 때
버그 이슈와 코멘트를 빠르게 훑고 핵심만 요약할 때
회의록이나 명세 문서에서 액션 아이템을 티켓으로 바꿀 때
이슈 상태와 배포/PR 맥락을 함께 확인하고 싶을 때

한 줄 정리
Jira가 팀의 일감을 정리하는 시스템이라면, JIRA MCP는 AI가 그 시스템 안에서 실제로 일하게 해주는 연결 장치입니다.

4. Harness Engineering이란 무엇인가

많은 개발자가 AI 코딩 도구를 처음 써보고 비슷한 경험을 합니다. 프롬프트를 꽤 잘 썼는데도 엉뚱한 파일을 고치거나, 팀 규칙을 무시하거나, 이미 정한 구조를 깨는 코드를 만들곤 합니다.

이때 흔히 “모델이 아직 부족해서 그래”라고 생각하기 쉽지만, OpenAI는 다른 관점을 제시합니다. 문제의 상당 부분은 모델 자체보다도 에이전트가 일하는 환경이 설계되지 않았기 때문이라는 것입니다.

Harness Engineering은 바로 그 환경을 설계하는 접근입니다. OpenAI는 이를 통해, 사람의 주된 역할이 직접 코드를 쓰는 것이 아니라 의도를 명확히 전달하고, 시스템을 설계하고, 피드백 루프를 만들어 AI가 안정적으로 일하게 하는 것으로 이동한다고 설명합니다.

쉽게 말해 하네스는 무엇인가

AI에게 “잘해봐”라고 던지는 것이 아니라, 어디까지 할 수 있는지, 무엇을 참고해야 하는지, 무엇이 틀렸는지 어떻게 알 수 있는지까지 포함해 작업 환경 전체를 설계하는 것입니다.

Harness Engineering의 핵심 요소

영역	왜 중요한가
문서화된 컨텍스트	AI는 레포 안에서 읽을 수 있는 정보만 제대로 활용할 수 있음
아키텍처 제약	AI가 아무 방향으로나 퍼지지 않도록 구조적 경계를 강제함
피드백 루프	린터, 테스트, 타입체커가 틀린 결과를 즉시 알려줌
관측성	로그, 메트릭, 트레이스를 볼 수 있어야 버그를 추적할 수 있음
SSOT	흩어진 정보 대신 저장소 안의 버전 관리된 지식을 기준으로 삼음

OpenAI는 특히 레포지토리 안의 지식을 시스템 오브 레코드(system of record)로 만드는 것을 강조합니다. 이유는 명확합니다. AI 에이전트 입장에서, 실행 시점에 접근할 수 없는 정보는 사실상 존재하지 않는 것과 같기 때문입니다.

회의록, 채팅방, 사람 머릿속에 있는 규칙은 에이전트가 안정적으로 참조할 수 없습니다.

그래서 AGENTS.md, CLAUDE.md, docs/architecture.md, ADR 같은 문서가 중요해집니다.

이 문서들은 사람이 보기 위한 참고자료이기도 하지만, 동시에 AI가 프로젝트를 이해하기 위한 맥락이 된다

중요한 포인트
AI 코딩의 품질은 프롬프트만으로 결정되지 않습니다. 더 좋은 결과는 더 긴 프롬프트보다 더 좋은 작업 환경에서 나온다는 것이 Harness Engineering의 핵심 메시지입니다.

5. GitOps는 왜 함께 이해해야 할까

GitOps는 Git 저장소를 시스템 상태의 Single Source of Truth로 삼고, 자동화된 에이전트가 실제 환경을 Git에 정의된 원하는 상태와 지속적으로 맞추는 운영 방식입니다.

OpenGitOps는 GitOps의 핵심 원칙을 선언적 구성, 버전화와 불변성, 자동 pull, 지속적 reconciliation으로 정리합니다.

이 개념이 왜 Harness Engineering과 연결될까요? 둘 다 같은 철학을 공유하기 때문입니다. 정답은 흩어진 설명이 아니라 저장소 안에 있어야 한다입니다. GitOps는 이를 인프라와 배포에 적용하고, Harness Engineering은 이를 AI 에이전트의 작업 환경 전반으로 확장합니다.

GitOps의 4가지 핵심 원칙

Declarative — 시스템이 어떤 상태여야 하는지 선언적으로 적는다
Versioned and Immutable — 원하는 상태는 Git에 버전 이력과 함께 남는다
Pulled Automatically — 소프트웨어 에이전트가 Git의 상태를 자동으로 가져온다
Continuously Reconciled — 실제 상태가 Git과 다르면 다시 맞춘다

예를 들어 Kubernetes 환경에서는 Argo CD 같은 도구가 대표적입니다. Argo CD는 자신을 “Kubernetes를 위한 선언적 GitOps Continuous Delivery 도구”로 설명하며, Git 저장소를 원하는 상태의 기준점으로 삼고 현재 클러스터 상태와 비교하여 어긋난 부분을 동기화합니다.

초보자 관점에서는 이렇게 이해하면 쉽습니다.
예전에는 운영자가 kubectl 명령으로 직접 바꿨다면, GitOps에서는 “어떤 상태가 되어야 하는지”를 Git에 커밋하고, 컨트롤러가 그 상태를 실제 환경에 맞춰 반영합니다.
그래서 변경 이력이 명확하고, 리뷰가 가능하며, 롤백도 쉬워집니다.

6. Visibility가 왜 사람과 AI 모두에게 중요한가

개발 팀에서 자주 나오는 질문이 있습니다. “이 버그는 어떤 티켓이었지?”, “이 변경은 어떤 PR로 들어갔지?”, “이게 지금 운영에 반영됐나?” 이런 질문에 답하려면 이슈, 코드, 빌드, 배포, 운영 지표가 서로 연결되어 있어야 합니다. 이 연결 상태를 잘 보여주는 능력이 바로 Visibility입니다.

가시성이 높은 팀에서는 하나의 이슈가 어떤 브랜치와 PR로 이어졌는지, 어떤 빌드가 돌았는지, 언제 배포됐는지, 그 뒤 운영 환경에서 어떤 상태를 보였는지까지 연결해서 볼 수 있습니다. Jira가 작업을 정리하고, MCP가 AI를 도구에 연결하고, GitOps가 배포 상태를 Git과 맞추면, 사람과 AI가 같은 사실을 기준으로 판단할 수 있는 환경이 만들어집니다.

결국 보이는 것이 관리된다
사람도, AI도, 보이지 않는 것은 제대로 다루기 어렵습니다.
그래서 좋은 개발 문화는 친절한 설명이 아니라, 잘 보이는 시스템을 만드는 쪽으로 발전합니다.

7. 처음 시작하는 개발자를 위한 실전 체크리스트

Level 1 — 개인 프로젝트에서 해볼 것

Jira에서 이슈, 보드, 스프린트 개념 익히기
프로젝트 루트에 AGENTS.md 또는 CLAUDE.md 만들어보기
README에 실행 방법, 테스트 방법, 폴더 구조 정리하기
린터와 포매터를 자동화해 AI와 사람이 같은 규칙을 쓰게 만들기

Level 2 — 팀 단위로 해볼 것

팀 규칙을 채팅방이 아니라 docs/ 디렉토리로 옮기기
아키텍처 규칙을 문서뿐 아니라 린터/테스트로 검증하기
Jira 이슈와 PR, 빌드, 배포를 연결해 흐름 보이게 만들기
MCP 기반 도구 연동을 검토해 AI가 실제 업무 도구를 읽게 만들기

Level 3 — 운영 환경까지 확장할 것

GitOps 도입으로 배포 상태를 Git 기준으로 정리하기
Argo CD나 유사 도구로 drift 감지와 동기화 자동화하기
로그, 메트릭, 트레이스를 AI가 읽을 수 있는 통로 설계하기
엔트로피 관리용 정리 루틴이나 에이전트 운영하기

8. 마무리: 이제 중요한 것은 ‘더 좋은 프롬프트’만이 아니다

많은 사람이 AI 활용을 이야기할 때 프롬프트 작성법부터 떠올립니다. 물론 그것도 중요합니다. 하지만 실제 팀 개발에서는 프롬프트보다 더 중요한 것이 있습니다. 바로 AI가 일할 수 있는 환경입니다.

Jira는 일을 구조화하고, MCP는 AI를 도구와 연결하고, JIRA MCP는 AI가 이슈 트래커 안에서 실제로 일할 수 있게 만들고, Harness Engineering은 그 AI가 흔들리지 않도록 맥락과 제약과 피드백 루프를 설계합니다.

그리고 GitOps는 코드와 인프라의 진실을 저장소 안에 고정해, 사람과 AI가 같은 기준을 보게 만듭니다.

좋은 AI 협업은 더 좋은 모델만으로 오지 않는다. 더 잘 설계된 개발 환경에서 나온다.

앞으로의 개발자는 단순히 코드를 많이 쓰는 사람보다, 사람과 AI가 함께 일할 수 있는 구조를 설계하는 사람이 더 강해질 가능성이 큽니다.
그래서 지금 이 주제들을 이해해두는 것은 단순한 신기술 공부가 아니라, 앞으로의 개발 방식 자체를 이해하는 일에 가까울거 같다.

참고 자료

[Git] "왜 이렇게 하나요?" 맥락으로 이해하는 팀 협업 브랜치 전략

0321ljh — Wed, 6 May 2026 11:38:02 +0900

1. 배경 및 문제 정의

규칙 없이 main 브랜치에만 푸시하는 팀은 반드시 사고를 마주합니다. 내 작업이 동료의 코드를 덮어쓰거나, 미완성 기능이 운영 서버에 섞여 들어가는 등의 문제는 '명령어'를 몰라서가 아니라 '전략'이 없어서 발생합니다.

브랜치 전략은 단순히 멋을 위한 것이 아니라, 사고 방지 장치이자 팀의 소통 규약입니다.

2. 해결 방안: 우리 팀에 맞는 브랜치 전략 선택

실무에서는 크게 두 가지 전략이 통용됩니다. 우리 서비스의 성격에 맞는 판단 기준을 세워야 합니다.

전략	특징	권장 상황
GitHub Flow	main + feature 구성 (단순)	빠른 배포가 필요한 웹 서비스, SaaS
Git Flow	5가지 브랜치로 엄격하게 관리	정기 릴리즈가 필요한 앱, 패키지 프로젝트

"작은 팀이나 스타트업은 GitHub Flow로 시작하고, 규모가 커지며 버전 관리가 복잡해질 때 Git Flow로 확장하는 것이 가장 실용적이다.."

3. PR(Pull Request) 워크플로우와 코드 리뷰

PR을 단순히 '머지 버튼'으로만 활용한다면 협업의 가치를 절반 이상 놓치는 것입니다. PR은 코드 리뷰를 시작하는 트리거이자, 6개월 뒤의 내가 읽을 변경 일기장입니다.

리뷰어가 좋아하는 PR 작성법

작게 쪼개라: 1,000줄짜리 PR은 집중력을 흐트러뜨립니다. 200~400줄 내외가 적당합니다.
제목은 한 줄로 명확히: [FIX] 로그인 토큰 만료 시 자동 리프레시 처리와 같이 타입과 목적을 명시하세요.
컨텍스트를 담아라: 무엇을(What), 왜(Why), 어떻게(How) 바꿨는지 상세히 기록해야 리뷰어의 시간을 아낄 수 있습니다.

4. Merge vs Rebase: 히스토리 통합 전략

히스토리를 있는 그대로 보존할 것인가, 아니면 한 줄로 깔끔하게 정리할 것인가의 차이입니다.

Merge: 두 브랜치의 히스토리를 보존합니다. 누가 어느 시점에 작업했는지 명확하지만 로그가 복잡해질 수 있습니다.
Rebase: 내 커밋을 대상 브랜치 끝에 옮겨 붙입니다. 로그가 직선형으로 깔끔해지지만, 커밋 해시가 변하므로 주의가 필요합니다.

Golden Rule: 이미 푸시되어 동료들과 공유 중인 브랜치는 절대 Rebase하지 마세요. 협업 환경을 파괴하는 행위가 될 수 있습니다.

5. 충돌(Conflict) 해결 프로세스

충돌은 에러가 아니라, Git이 사람의 판단을 요청하는 신호입니다. 빨간 문구에 당황하지 말고 아래 5단계를 따르세요.

상태 확인: git status로 충돌 파일 식별
마커 찾기: <<<<<<< HEAD와 ======= 사이의 코드 대조
수정: 원하는 코드로 병합 및 마커 제거
스테이징: git add .
커밋: git commit으로 머지 완료

6. 회고

명령어를 암기하는 것보다 "왜 이렇게 하는가"의 맥락을 잡는 것이 중요한거 같다.

MSA프로젝트 시작

0321ljh — Wed, 6 May 2026 10:39:57 +0900

git 저장소 기본 필수적인 뼈대 6개 생성.

저장소를 클론 받기 위해 큰 폴더를 만들고 cmd창에 들어가 git clone

https://start.spring.io/

에 접속을 해 공통 설정을 해준다

Java: 17

1. eureka-server
- Eureka Server
- Spring Boot Actuator
2. config-server
- Config Server
- Spring Boot Actuator
3. api-gateway
- Gateway
- Eureka Discovery Client
- Config Client
- Spring Boot Actuator
4. user-service
- Spring Web
- Spring Data JPA
- PostgreSQL Driver
- Eureka Discovery Client
- Config Client
- OpenFeign
- Spring Boot Actuator
- Validation
- Lombok
5. common-module (공통 라이브러리)
- Spring Web
- Lombok
- (주의: DB나 클라이언트 관련 라이브러리는 하위 서버들과의 스캔 충돌 방지를 위해 절대 넣지 마세요!)
주의사항: config-hub는 스프링 프로젝트가 아니다.

Spring Web (REST API 구현용)
Spring Data JPA (DB ORM)
PostgreSQL Driver (발제문 권장 DB)
Eureka Discovery Client
Config Client
OpenFeign (발제문 요구사항: 서비스 간 통신 기본 구성)
Spring Boot Actuator
Validation (발제문 요구사항: 데이터 유효성 검사)
Lombok (코드 간소화)
Zipkin (분산 추적)

주의사항: common-module에는 절대로 DB(JPA, PostgreSQL)나 클라우드(Eureka, Feign) 관련 의존성을 넣으면 안된다.

다른 서비스들이 이 모듈을 가져다 쓸 때 원치 않는 자동 설정(Auto-configuration) 충돌이 발생할 수 있음

프로젝트 시작

0321ljh — Wed, 6 May 2026 10:37:28 +0900

[MSA] wherelsMyParcel 프로젝트 시작 Actuator 검증

MSA(Microservice Architecture) 프로젝트 'DelivHub'의 첫 삽을 떴습니다. 비즈니스 로직을 구현하기 전, 가장 먼저 진행한 작업은 팀원들이 안정적으로 개발할 수 있는 인프라 기반을 닦고, 서비스의 생존 여부를 확인할 수 있는 지표를 확보하는 것이었습니다.

1. 인프라 초기 설정: 왜 Java 21인가?
2. 서비스별 의존성(Dependency) 설계 전략
3. 실전 구축: Actuator를 활용한 Health Check
4. 트러블슈팅: 라이브러리 제거와 코드 정합성
5. 마치며: 기초가 튼튼한 MSA

1. 인프라 초기 설정: 왜 Java 21인가?

프로젝트의 핵심 스택을 결정하는 것은 성능과 유지보수성을 좌우합니다. 이번 DelivHub 프로젝트는 Java 21과 Spring Boot 3.3.x를 선택했습니다.

항목	선택한 설정값
Project / Language	Gradle - Groovy / Java 21 (LTS)
Spring Boot	3.3.x (Stable)
Packaging / DB	Jar / PostgreSQL

Senior's Insight: Java 21을 선택한 전략적 이유

Java 17: 안정적이지만 최신 기능(Virtual Threads 등)을 활용할 수 없습니다.
Java 25(최신): 성능은 기대되나, 아직 서드파티 라이브러리(Spring AI, Zipkin 등)와의 호환성 버그 가능성이 있어 부트캠프나 단기 프로젝트에선 리스크가 큽니다.
Java 21: 현재 실무에서 가장 권장되는 최신 LTS 버전으로, 레퍼런스가 풍부하고 호환성이 완벽히 검증된 가장 합리적인 선택입니다.

2. 서비스별 의존성(Dependency) 설계 전략

5개의 마이크로서비스가 유기적으로 움직이기 위해 각 서비스의 책임에 맞는 의존성만 깔끔하게 할당했습니다.

핵심 서비스 구성

Eureka Server: 서비스들의 위치를 관리하는 전화번호부 역할
Config Server: 모든 서비스의 설정값(.yml)을 중앙에서 관리
API Gateway: 클라이언트의 요청을 적절한 서비스로 라우팅
User-Service: 사용자 비즈니스 로직 담당 (템플릿 서버)
Common-Module: 전 서비스에서 공통으로 사용할 유틸리티 및 DTO

주의사항: Common-Module 설계의 핵심 common-module에는 절대로 DB(JPA, PostgreSQL)나 클라우드(Eureka, Feign) 관련 의존성을 넣어서는 안 됩니다.
공통 모듈에 무거운 의존성이 포함되면, 이를 참조하는 다른 서비스들에서 '원치 않는 자동 설정(Auto-configuration)' 충돌이 발생해 빌드 오류가 남.

❓ Config-Hub는 무엇인가요? 스프링 프로젝트가 아닌 '설정 데이터베이스(보관소)'이다.
실제 코드 없이 user-service.yml 같은 설정 파일만 담고 있으며, Config Server가 이곳에서 데이터를 읽어와 각 서비스에 전달

3. 실전 구축: Actuator를 활용한 Health Check

MSA 환경에선 서비스 하나가 죽으면 도미노처럼 장애가 번집니다. 이를 방지하기 위해 Spring Boot Actuator를 도입해 가동 지표를 확보했습니다.

Step 1: 포트 규칙 정의

충돌 방지를 위해 팀원들과 포트 규칙을 미리 정했습니다. User-Service는 8081을 사용합니다.

Step 2: 의존성 및 설정

application.yaml server:
  port: 8081

management:
  endpoints:
    web:
      exposure:
        include: health
  endpoint:
    health:
      show-details: always

4. 트러블슈팅: 라이브러리 제거와 코드 정합성

❌ 이슈 발생: 컴파일 오류 (Symbol not found) 의존성을 경량화하기 위해 build.gradle에서 Spring Cloud 관련 라이브러리를 제거했는데, 코드에는 여전히 @EnableDiscoveryClient 어노테이션이 남아있어 발생한 문제입니다.

Lesson Learned: 라이브러리를 걷어낼 때는 설정 파일(Gradle/Maven)뿐만 아니라 소스 코드 내의 Annotation과 Import 문까지 세트로 정리해야 한다.

5. 마치며: 기초가 튼튼한 MSA

서버 기동 후 GET http://localhost:8081/actuator/health를 통해 "status": "UP"이라는 응답을 확인

Success Response {
  "status": "UP",
  "components": {
    "diskSpace": { "status": "UP", ... },
    "ping": { "status": "UP" }
  }
}