개발 끄적임 노트

RDS 인스턴스 업그레이드 후 Firebase Functions 연결 장애 - HAProxy 트러블슈팅

smink — Sat, 9 May 2026 09:30:55 +0900

RDS 인스턴스 업그레이드 후 Firebase Functions 연결 장애 — HAProxy DNS 캐싱 트러블슈팅

HAProxy 트러블 슈팅

상황

RDS 인스턴스를 t4g.xlarge에서 m7g.2xlarge로 업그레이드했다. 업그레이드 직후부터 Firebase Functions에서 다음 에러가 발생하기 시작했다.

Unhandled error Error: Connection lost: The server closed the connection.
    at Object.createConnection (mysql2/promise.js:253:31)
    ...
    code: 'PROTOCOL_CONNECTION_LOST'

증상 정리

항목	상태
EKS 서비스 → RDS (Spring Boot, Ruby)	✅ 정상
Bastion → RDS 직접 접속	✅ 정상
NLB Target Group 헬스체크	✅ 정상
Firebase Functions → RDS	❌ 연결 끊김
NLB 활성 플로우 수	한 자리수로 급감

EKS에서 실행 중인 Spring Boot, Ruby 서버는 RDS에 직접 연결하기 때문에 이번 장애에서 완전히 영향을 받지 않았다. Firebase Functions 경유 기능만 중단된 것이다.

원인을 찾아가는 과정

1단계: 어디서 끊기는가

EKS 서비스와 Bastion에서 RDS 직접 접속이 모두 정상이었으므로, RDS 자체는 문제없다는 것이 명확했다. 장애 범위가 Firebase Functions → HAProxy → RDS 경로로 좁혀졌다.

Firebase Functions → NLB ✅ → HAProxy EC2 ✅ → RDS ✅
                                    ↑
                               여기서 뭔가 잘못됨

NLB 헬스체크도 정상이었다. HAProxy 프로세스 자체는 살아있다는 의미다.

2단계: HAProxy 설정 확인

HAProxy EC2에 직접 접속해서 설정을 확인했다.

backend be_service_db
    mode tcp
    option tcp-check
    server rds [RDS_ENDPOINT]:3306 check

헬스체크 주기가 별도로 설정되어 있지 않았다. HAProxy 기본값은 2초마다 헬스체크를 수행하고 rise 2(연속 2회 성공 시 UP)이므로, 이론상 RDS가 복구된 후 최대 4초 안에 자동 감지가 되어야 한다.

그런데 자동 복구가 되지 않았다.

3단계: 처음 세운 가설 — TCP/MySQL 타이밍 문제

option tcp-check는 3306 포트가 열렸는지만 확인한다. RDS 재시작 시 TCP 포트가 먼저 열리고 MySQL이 나중에 준비되는 타이밍 차이 때문에 자동 복구가 안 됐을 거라고 생각했다.

RDS 재시작
    ↓
TCP 포트 3306 오픈    ← HAProxy "살아났다!" 판정
    ↓
MySQL 초기화 진행 중  ← 실제로는 아직 준비 안 됨
    ↓
연결 즉시 끊김

그럴듯한 가설이었지만, 실제 로그를 확인해보니 달랐다.

TCP 포트 자체가 열리지 않았다. TCP/MySQL 타이밍 차이 문제가 발생하려면 TCP 포트가 먼저 열려야 하는데, 이번 경우는 포트 자체에 도달조차 못한 상황이었다.

실제 원인: HAProxy DNS 캐싱

RDS 인스턴스 클래스 변경 시 내부 IP가 바뀐다

RDS 인스턴스 클래스를 변경하면 DNS 엔드포인트 주소는 동일하게 유지되지만, 내부 IP 주소는 변경된다.

변경 전: [RDS_ENDPOINT].rds.amazonaws.com → x.x.x.10
변경 후: [RDS_ENDPOINT].rds.amazonaws.com → x.x.x.55  ← IP 변경

처음엔 "엔드포인트가 같으니 문제없겠지"라고 생각했지만, 문제는 엔드포인트가 아니라 HAProxy가 그 엔드포인트를 어떻게 다루는가에 있었다.

HAProxy는 DNS를 기동 시점에 1회만 조회한다

HAProxy는 서버 항목의 DNS를 기동 시점에 단 한 번만 조회하여 IP를 내부적으로 고정 저장한다. 이는 HAProxy 공식 문서에도 명시된 기본 동작이다.

HAProxy 기동
    ↓
[RDS_ENDPOINT] → x.x.x.10 (구 IP) 조회 및 고정 저장
    ↓
RDS 인스턴스 클래스 변경 → 내부 IP가 x.x.x.55 로 변경
    ↓
HAProxy는 여전히 x.x.x.10 으로 헬스체크 및 연결 시도
    ↓
TCP 포트 자체에 도달하지 못함 → Connection Refused 반복
    ↓
아무리 시간이 지나도 자동 복구 불가

헬스체크가 2초마다 정상적으로 돌고 있었지만, 이미 사라진 구 IP로 계속 확인하고 있었기 때문에 영원히 복구될 수 없는 상태였던 것이다.

reload가 즉시 복구된 이유

sudo systemctl reload haproxy가 즉시 복구 트리거가 됐다.

reload는 HAProxy가 설정을 재적용하면서 DNS를 새로 조회하는 동작을 수반한다. 설정 변경 없이 reload만으로 즉시 복구됐다는 사실 자체가 DNS 캐싱이 원인이었음을 역으로 증명한다.

NLB 헬스체크 vs HAProxy 내부 헬스체크

이번 장애에서 헷갈렸던 포인트가 있다.

헬스체크 주체	대상	확인 내용	이번 결과
NLB TG 헬스체크	NLB → HAProxy 포트 9000	HAProxy 프로세스가 살아있는지	✅ 정상
HAProxy 내부 헬스체크	HAProxy → RDS 포트 3306	RDS IP로 연결 가능한지	❌ 구 IP로 시도 중

NLB 헬스체크가 정상이어도 HAProxy 내부에서 잘못된 IP로 연결을 시도하면 실제 트래픽은 전부 실패한다. NLB 헬스체크 정상이 곧 DB 연결 정상을 의미하지 않는다.

재발 방지: resolvers 설정 추가

헬스체크 주기 조정이 아닌, HAProxy에 DNS 동적 재조회 설정(resolvers) 을 추가하는 것이 근본 해결책이다.

/etc/haproxy/haproxy.cfg 수정:

resolvers awsdns
    nameserver dns1 169.254.169.253:53   # AWS VPC 내부 DNS, 모든 VPC에 기본 제공하는 공용 DNS 서버 주소
    resolve_retries 3
    timeout resolve 1s
    timeout retry   1s
    hold valid 10s                        # DNS 캐시 10초만 유지

backend be_service_db
    mode tcp
    option tcp-check
    default-server inter 2s rise 2 fall 3 init-addr none resolvers awsdns resolve-prefer ipv4
    server rds [RDS_ENDPOINT]:3306 check

핵심 설정:

resolvers awsdns: AWS VPC DNS(169.254.169.253)를 사용하는 resolver 블록 정의
hold valid 10s: DNS 캐시를 10초만 유지, 이후 재조회
init-addr none: 기동 시 DNS 조회 결과를 고정하지 않음
resolve-prefer ipv4: IPv4 주소 우선 사용

# 문법 검사
sudo haproxy -c -f /etc/haproxy/haproxy.cfg

# 무중단 리로드
sudo systemctl reload haproxy

이 설정 적용 후에는 향후 RDS IP가 변경되더라도 HAProxy가 자동으로 감지하여 수동 개입 없이 복구된다.

교훈

RDS 인스턴스 클래스 변경 시 내부 IP가 바뀐다: DNS 엔드포인트가 동일해도 IP는 변경된다. HAProxy처럼 DNS를 캐싱하는 미들웨어가 끼어 있다면 반드시 고려해야 한다.
HAProxy는 기본적으로 DNS를 캐싱한다: 공식 문서에 명시된 기본 동작이다. resolvers 설정 없이는 IP 변경을 자동으로 감지하지 못한다.
그럴듯한 가설도 로그로 검증해야 한다: TCP/MySQL 타이밍 문제를 의심했지만, 실제로는 TCP 포트 자체에 도달하지 못하는 상황이었다. 증상만 보고 원인을 단정하지 말 것.
reload의 동작 원리를 알면 원인이 보인다: reload가 즉시 복구 트리거가 됐다는 사실 자체가 DNS 캐싱이 원인이었음을 증명한다.
NLB 헬스체크 정상 ≠ HAProxy 내부 연결 정상 ≠ DB 연결 정상: 헬스체크 레이어가 여러 단계임을 인식해야 한다.

Firebase Functions와 AWS RDS 연결(HAProxy + NLB 구조 설계)

smink — Fri, 8 May 2026 17:08:26 +0900

HAProxy를 통한 Firebase Functions와 AWS RDS 연결

배경

자사 서비스의 핵심 백엔드는 EKS(Kubernetes) 위에서 운영되며, EKS 애플리케이션들은 프라이빗 서브넷 내에서 RDS에 직접 연결한다.

그런데 일부 기능은 Firebase Functions로 운영되고 있다. Firebase Functions는 Google Cloud 위에서 실행되기 때문에 AWS VPC 안에 있는 RDS에 직접 접근할 수 없다.

이 글은 Firebase Functions에서 AWS RDS로 접근하기 위해 HAProxy + NLB 구조를 설계한 과정을 다룬다.

왜 직접 연결이 안 되는가

RDS는 프라이빗 서브넷에 위치해 있다. 외부 인터넷에서 직접 접근할 수 없도록 의도적으로 격리된 구조다.

Firebase Functions는 Google Cloud의 서버리스 환경에서 실행되며, 고정 IP가 없고 AWS VPC 내부 네트워크에 속하지 않는다. 따라서 VPC 내부 리소스인 RDS에 직접 붙는 것이 불가능하다.

같은 VPC 안에 있는 EKS 노드는 직접 연결이 가능하지만, Google Cloud에서 실행되는 Firebase Functions는 별도의 경로가 필요하다.

선택한 구조: HAProxy + NLB

Firebase Functions (Google Cloud)
        │
        │  TCP :13306 (인터넷)
        ▼
┌───────────────────────────┐
│   NLB (공개 서브넷)          │  ← 인터넷에서 접근 가능한 진입점
│   포트 13306 수신           │
└──────────────┬────────────┘
               │  TCP :13306 (VPC 내부)
               ▼
┌───────────────────────────┐
│   HAProxy EC2 (ASG)       │  ← 프라이빗 앱 서브넷
│   프라이빗 서브넷             │
│   13306 → 3306 포워딩       │
└──────────────┬────────────┘
               │  TCP :3306 (VPC 내부)
               ▼
┌───────────────────────────┐
│   RDS MySQL               │  ← 프라이빗 DB 서브넷
│   프라이빗 DB 서브넷          │
└───────────────────────────┘

각 구성요소 역할

NLB (Network Load Balancer)

인터넷에 공개된 진입점
포트 13306으로 들어오는 TCP 트래픽을 수신
HAProxy EC2 인스턴스로 포워딩

HAProxy EC2 (Auto Scaling Group)

프라이빗 서브넷에 위치 — 외부 직접 접근 불가
NLB에서 받은 13306 트래픽을 RDS의 3306으로 포워딩
ASG로 구성되어 있어 인스턴스 장애 시 자동 교체
포트 9000: NLB 헬스체크 전용 엔드포인트

RDS MySQL

프라이빗 DB 서브넷에 위치
Security Group으로 접근 제어

HAProxy 설정

frontend fe_service_db
    bind *:13306
    mode tcp
    timeout client 30s
    default_backend be_service_db

backend be_service_db
    mode tcp
    option tcp-check
    server rds [RDS_ENDPOINT]:3306 check

포트 9000은 NLB 헬스체크를 위한 HTTP 엔드포인트다.

frontend fe_healthcheck
    bind *:9000
    mode http
    http-request return status 200 content-type "text/plain" lf-string "OK\n"

포트 번호를 3306이 아닌 13306으로 쓴 이유

표준 MySQL 포트(3306)를 외부에 그대로 노출하면 자동화된 포트 스캔 공격의 타겟이 되기 쉽다. 13306은 동일한 TCP 프록시 역할을 하되, 포트 번호만 다르게 운영하는 보안 관행이다.

NLB 헬스체크 구조

NLB는 HAProxy의 포트 9000을 헬스체크 대상으로 사용한다. HAProxy가 정상 실행 중이면 200 OK를 응답한다.

이 구조 덕분에 HAProxy 프로세스가 죽으면 NLB가 해당 인스턴스를 자동으로 Unhealthy 처리하고, ASG가 새 인스턴스로 교체한다.

보안 설계

구간	허용 트래픽
인터넷 → NLB	TCP 13306 전체 허용
NLB → HAProxy EC2	TCP 13306, 9000 (VPC CIDR 내부)
HAProxy EC2 → RDS	TCP 3306 (Security Group)
EKS 노드 → RDS	TCP 3306 (Security Group)
Bastion → RDS	TCP 3306 (관리용)

RDS Security Group은 HAProxy EC2, EKS 노드, Bastion에서 오는 3306 트래픽만 허용한다. Firebase Functions는 HAProxy를 경유하므로 별도 허용 없이 접근이 가능하다.

정리

Firebase Functions처럼 외부 클라우드 환경에서 프라이빗 VPC 리소스에 접근해야 할 때, VPN이나 VPC Peering 없이도 NLB + HAProxy 조합으로 안전하게 중간 브릿지를 구성할 수 있다.

다음 글에서는 이 구조에서 RDS 인스턴스 업그레이드 후 발생한 장애와 해결 과정을 다룰 예정이다.

AWS 전체 인프라 구조 (Terraform 모듈 기반)

smink — Fri, 8 May 2026 16:51:47 +0900

AWS 인프라 전체 구조 — Terraform으로 관리하는 VPC 설계

개요

AWS 인프라는 Terraform으로 관리되며, 총 13개의 모듈로 구성되어 있다.

cloudfront / ec2-bastion / eks / eks_node_alarm / eks-addon
irsa / network / nodegroup / notifications / rds
rds_alarm / rds-proxy-server / s3

서비스의 핵심 트래픽은 EKS Cluster에서 처리되며, 모든 애플리케이션은 프라이빗 DB 서브넷의 RDS MySQL에 직접 연결된다. Firebase Functions는 별도의 HAProxy 경유 경로를 사용한다.

VPC 네트워크 구조

리전: ap-northeast-2 (서울)

서브넷 구성

서브넷	종류	용도
SBN-pub-a, SBN-pub-c	공개 (Public)	Bastion, NLB, NAT Gateway
SBN-priv-APP-a, SBN-priv-APP-c	프라이빗 (App)	EKS 노드, HAProxy EC2
SBN-priv-DB-a, SBN-priv-DB-c	프라이빗 (DB)	RDS MySQL

라우팅

공개 서브넷: Internet Gateway를 통해 인터넷과 직접 통신
프라이빗 서브넷: NAT Gateway를 통해 아웃바운드 인터넷 통신 (인바운드 차단)

컴포넌트별 상세

1. EKS Cluster (메인 서비스)

컨테이너 기반 서비스를 운영하는 쿠버네티스 클러스터다. 인터넷 사용자의 모든 요청이 이곳에서 처리된다.

위치: 프라이빗 앱 서브넷
인증: API 모드 (ConfigMap 비활성화)
IRSA: OIDC Provider를 통해 파드별 IAM 역할 부여
Bastion에서 kubectl로 관리

노드 그룹 구성

총 3개의 노드 그룹이 역할별로 분리 운영된다. Bastion 포함 상시 5개 인스턴스가 구동된다.

노드 그룹	배포 서비스	RDS 연결	Desired	Min	Max
App	Spring Boot API, Ruby API	MySQL	2	2	4
Web	Spring Boot API, React	MySQL	1	1	2
Test	테스트 서버	MySQL	1	1	2

모든 애플리케이션(Spring Boot, Ruby 등)은 프라이빗 앱 서브넷에서 프라이빗 DB 서브넷의 RDS에 직접 연결한다.

App 노드 그룹 (Desired: 2)

핵심 API 서버 2종이 함께 운영되어 Desired를 2로 설정
트래픽 증가 시 최대 4개까지 자동 확장

Web 노드 그룹 (Desired: 1)

홈페이지 서버와 React 정적 서빙을 담당

Test 노드 그룹 (Desired: 1)

스테이징/테스트 목적으로 분리 운영

2. CloudFront + S3

정적 파일(이미지, 에셋 등)을 제공하는 CDN 레이어다.

Origin: S3 버킷, OAC(Origin Access Control)로 CloudFront에서만 접근 가능
HTTPS: ACM 인증서 적용, TLSv1.2 이상 강제
캐싱: 커스텀 캐시 정책 (TTL, 쿼리스트링/헤더/쿠키 설정 가능)

3. Bastion EC2

VPC 내부 리소스 관리를 위한 점프 서버다.

위치: 공개 서브넷, Elastic IP 보유
역할: RDS 직접 접속, EKS kubectl 관리
EKS Admin 권한으로 등록되어 kubectl 사용 가능

4. RDS Proxy Server (HAProxy + NLB)

Firebase Functions와 RDS를 연결하는 보조 경로다.

NLB: 인터넷 facing, 공개 서브넷, 포트 13306
HAProxy EC2: Auto Scaling Group, 13306 → 3306 포워딩 (Firebase 전용 경로)
포트 9000: NLB 헬스체크 전용 HTTP 엔드포인트

5. RDS MySQL

서비스 전체 애플리케이션이 공유하는 메인 데이터베이스다.

위치: 프라이빗 DB 서브넷 (2 AZ)
인스턴스: m7g.2xlarge
접근 경로:
- EKS 애플리케이션 (Spring Boot, Ruby 등) → 직접 연결
- Firebase Functions → NLB → HAProxy → RDS
- Bastion → 직접 연결 (관리용)
deletion_protection = true, performance_insights_enabled = true
삭제 시 final snapshot 자동 생성

보안 설계 원칙

공개 서브넷        →  IGW 통해 인터넷 직접 통신
프라이빗 앱 서브넷  →  NAT GW 아웃바운드만, 인바운드는 EKS Ingress / NLB / Bastion 경유
프라이빗 DB 서브넷  →  NAT GW 아웃바운드만, 인바운드는 앱 서브넷만 허용

RDS: HAProxy EC2, EKS 노드, Bastion만 3306 허용
NLB: 포트 13306만 외부 공개
EKS: 퍼블릭 엔드포인트는 허용 CIDR 제한

모니터링 & 알람

모듈	역할
`rds_alarm`	RDS CPU, 연결 수, 스토리지 CloudWatch 알람
`eks_node_alarm`	EKS 노드 CPU, 메모리 알람
`notifications`	SNS/슬랙 등 알림 발송

Terraform 모듈 구조

network          → VPC, 서브넷, IGW, NAT GW, 라우팅 테이블
ec2-bastion      → Bastion EC2, EIP, IAM Role, SG
rds              → RDS 인스턴스, Subnet Group, SG
rds-proxy-server → HAProxy EC2 (ASG + Launch Template), NLB, TG
eks              → EKS 클러스터, IAM, OIDC Provider
nodegroup        → 워커 노드 그룹 (app / web / test)
eks-addon        → EKS 애드온 (CoreDNS, kube-proxy, VPC CNI 등)
irsa             → 서비스 어카운트별 IAM Role
cloudfront       → CloudFront Distribution, 캐시 정책
s3               → S3 버킷
rds_alarm        → RDS CloudWatch 알람
eks_node_alarm   → EKS 노드 알람
notifications    → SNS, 알람 라우팅

Kubernetes,K8s,K3s ImagePullBackOff - ECR 인증(regcred) 오류 원인, 해결법

smink — Tue, 25 Nov 2025 15:36:28 +0900

문제 상황

테스트 서버에서 특정 Deployment의 Pod가 ImagePullBackOff 상태로 Pending, kubectl describe pod에서 반복적인 Back-off pulling image 이벤트를 확인하였다.

kubectl get pods

ImagePullBackOff는 원인이 다양하기 때문에 먼저 아래 항목을 확인했다.

Deployment에 imagePullSecrets가 설정되어 있는가?
- spec.template.spec.imagePullSecrets에 regcred가 있어야 함.
Secret(regcred)이 올바른 네임스페이스에 있는가?
- Pod와 Secret은 동일 namespace여야 함.
Secret 내부 .dockerconfigjson 구조가 정확한가?
- auths에 레지스트리 도메인이 정확히 들어가 있어야 함.
이미지가 레지스트리에 실제로 존재하는가?
- ECR에 해당 태그가 push 되어 있는지 확인.
노드(EC2)의 IAM 역할에 ECR Pull 권한이 있는가?
- AmazonEC2ContainerRegistryReadOnly 등 권한 필요.

Pod가 ImagePullBackOff 상태에 빠졌고, 원인은 Kubernetes가 사용하는 imagePullSecret(regcred)에 들어간 Docker 인증 정보가 잘못된 파일을 참조한 것이었다. 원인은 Docker가 snap으로 설치되어 config.json 경로가 달라졌기 때문이며, 올바른 config.json으로 regcred를 다시 생성하고 Deployment를 재시작하여 문제를 해결했다.

확인 과정

Pod 상태 확인

kubectl describe pod <pod-name>

Deployment 확인

kubectl get deploy <deployment-name> -o yaml

(여기서 imagePullSecrets: - name: regcred 가 정상 존재함을 확인)

Secret의 실제 내용(디코딩) 확인

kubectl get secret regcred -o jsonpath='{.data.\.dockerconfigjson}' | base64 --decode

→ 출력에서 auths에 들어간 도메인이 Deployment 이미지 도메인과 정확히 일치하는지 확인.

Docker 로그인 과정 확인(로그 메세지에서 단서 발견): GitHub Actions 또는 EC2에서 docker login 로그에서 다음과 같은 경고 발견

WARNING! Your credentials are stored unencrypted in '/home/***/snap/docker/3377/.docker/config.json'.

→ 이는 Docker가 snap으로 설치되어 실제 config.json 경로가 /home/ubuntu/snap/docker/current/.docker/config.json 등 snap 경로를 사용한다는 뜻.

실제 snap 디렉터리 확인

ls -al /home/ubuntu/snap/docker/

→ current가 3377으로 링크되어 있었음. 즉 실제 config 파일은 .../snap/docker/current/.docker/config.json 에 존재.

✅ ImagePullBackOff는 Kubernetes가 잘못된 Docker 인증 파일(config.json) 경로로 만들어진 regcred를 사용해 ECR 인증에 실패했기 때문에 발생했다. (구체적으로, Docker가 snap 경로의 config.json을 이용했음에도 regcred를 일반 경로 파일로 만들어 인증 정보가 비어 있거나 잘못된 상태였음)

해결 방법 ( 실제 진행 절차)

1. 잘못 생성된 regcred 삭제

kubectl delete secret regcred -n default

2. snap 경로의 실제 config.json을 사용해 regcred 재생성

kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=/home/ubuntu/snap/docker/current/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson \
  --namespace=default

3. 생성된 secret 내용 확인(디코딩)

kubectl get secret regcred -n default -o jsonpath='{.data.\.dockerconfigjson}' | base64 --decode

→ 출력에서 auths 아래에 <AWS_ACCOUNT_ID>.dkr.ecr.ap-northeast-2.amazonaws.com 같은 도메인이 정확히 있는지 확인

4. Deployment 재시작(새 Pod가 새로운 secret을 사용하게 함)

kubectl rollout restart deployment <deployment-name> -n default

5. 복구 확인

kubectl get pods -n default
kubectl describe pod <new-pod-name> -n default

더 이상 ImagePullBackOff가 뜨지 않고 Running 상태로 전환됨을 확인

예방 방법(다시는 같은 문제를 안 겪으려면)

Docker 설치 방식(snap vs apt) 확인하고 config.json의 실제 경로를 파악할 것
regcred 생성은 항상 해당 호스트에서 실제로 Docker가 사용하는 config.json으로 만들 것
CI/CD(예: GitHub Actions)에서 Secret을 생성·업데이트한다면 그 과정의 config.json을 별도로 보관하거나, K8s에 직접 kubectl create secret을 실행하도록 자동화할 것
kubectl get secret regcred -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d 로 생성 직후 내용 확인 습관화
배포 자동화 시 kubectl rollout restart를 자동 트리거하여 새 Secret 반영을 보장

결론

ImagePullBackOff는 다양한 원인이 있으나, 이번 케이스는 잘못된 config.json 경로로 인해 regcred가 올바른 인증정보를 담지 못한 문제였다. snap으로 설치된 Docker의 config 위치를 정확히 반영해 regcred를 재생성하고 Deployment를 재시작하면 문제가 해결된다.

# 1) 기존 secret 삭제
kubectl delete secret regcred -n default

# 2) snap 경로의 config.json으로 secret 생성
kubectl create secret generic regcred \
  --from-file=.dockerconfigjson=/home/ubuntu/snap/docker/current/.docker/config.json \
  --type=kubernetes.io/dockerconfigjson \
  --namespace=default

# 3) secret 내용 확인
kubectl get secret regcred -n default -o jsonpath='{.data.\.dockerconfigjson}' | base64 --decode

# 4) 배포 재시작
kubectl rollout restart deployment <deployment-name> -n default

# 5) 상태 확인
kubectl get pods -n default
kubectl describe pod <pod-name> -n default

[Docker Hub, GitHub Actions] ERROR: failed to build: failed to solve: openjdk:17-jdk: failed to resolve source metadata for docker.io/library/openjdk:17-jdk: docker.io/library/openjdk:17-jdk: not found

smink — Tue, 4 Nov 2025 17:42:13 +0900

잘 동작중이던 GitHub Action이 오늘 갑자기 아래와 같은이유로 실패를 하였다.

#0 building with "default" instance using docker driver
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 188B done
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/openjdk:17-jdk
#2 ...
#3 [auth] library/openjdk:pull token for registry-1.docker.io
#3 DONE 0.0s
#2 [internal] load metadata for docker.io/library/openjdk:17-jdk
#2 ERROR: docker.io/library/openjdk:17-jdk: not found
------
 > [internal] load metadata for docker.io/library/openjdk:17-jdk:
------
Dockerfile:1
--------------------
   1 | >>> FROM openjdk:17-jdk
   2 |     
   3 |     COPY build/libs/*SNAPSHOT.jar app.jar
--------------------
ERROR: failed to build: failed to solve: openjdk:17-jdk: failed to resolve source metadata for docker.io/library/openjdk:17-jdk: docker.io/library/openjdk:17-jdk: not found
Error: Process completed with exit code 1.

% docker manifest inspect openjdk:17-jdk                 
no such manifest: docker.io/library/openjdk:17-jdk

위 명령어를 통해 해당 이미지가 사라진지 확인해보았고, 찾을 수 없다는것 까지도 알게되었다...

https://hub.docker.com/_/openjdk 에서 확인을 해보니, 17버전에 대한 지원 중단 이야기가 몇년전에 나와있었고, 오늘에서야 지원이 중단된 듯 하다.

openjdk - Official Image | Docker Hub

Docker Official Images are a curated set of Docker open source and drop-in solution repositories. Why Official Images? These images have clear documentation, promote best practices, and are designed for the most common use cases.

hub.docker.com

태그 올라온 것들을 보면 특정 버전으론 여전히 이미지가 제공되고 있는것 같아보인다.

결국 이를 해결하기 위해서 기존의 openjdk 대신 amazoncorretto로 변경을 하였다.

# FROM openjdk:17-jdk # 과거 사용중이던 openjdk image -> 중단됨
FROM amazoncorretto:17 # 새롭게 바꾼 amazoncorretto image

COPY build/libs/*SNAPSHOT.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app.jar"]

이후에 다시 Github Action을 동작시켰고, 바로 문제없이 성공한걸 확인할 수 있었다.

Run docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
#0 building with "default" instance using docker driver

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 191B done
#1 DONE 0.0s

#2 [internal] load metadata for docker.io/library/amazoncorretto:17
#2 ...

#3 [auth] library/amazoncorretto:pull token for registry-1.docker.io
#3 DONE 0.0s

#2 [internal] load metadata for docker.io/library/amazoncorretto:17
#2 DONE 0.9s

# 생략...

[AWS RDS] pt-query-digest를 활용한 slow query 분석

smink — Mon, 1 Sep 2025 14:30:00 +0900

문제 상황

RDS에서 slow_query_log를 켜둔 상태였는데, 로그가 수만 건 이상 쌓여 관리가 어려워짐
로그를 직접 보면 조건값이 조금씩 달라서 전부 다른 쿼리처럼 보임
실제로는 같은 쿼리 패턴인데 단순 값 차이 때문에 중복 로그처럼 쌓이고 있었음

즉, 비슷한 쿼리를 묶어서 패턴화하지 않으면 개선 포인트를 찾기 어려운 상황

해결 방법

저는 크게 두 가지 단계를 거쳐 문제를 해결했습니다.

로그 파일 다운로드
- AWS Console에서 RDS 인스턴스를 선택하고 '로그 및 이벤트' 탭으로 이동
- slowquery/mysql-slowquery.log 파일을 다운로드
로그 분석
- Percona Toolkit의 pt-query-digest를 이용해 쿼리를 패턴화 & 집계
- 상위 몇 개의 문제 쿼리만 집중적으로 튜닝

pt-query-digest 사용하기

pt-query-digest

1. 설치

MacOS/Linux 환경에서 아래 명령어를 통해 설치

brew install percona-toolkit
또는
sudo apt-get install percona-toolkit

2. 실행

pt-query-digest slowquery.log > slowquery_report.txt

단 한 줄로 수만 건의 로그가 깔끔한 리포트로 변환됩니다

분석 리포트

아래는 실제 일부 로그만을 pt-query-digest 통해 분석한 결과의 일부입니다.

pt-query-digest 통한 분석 결과 일부

27 total → 총 27번 실행된 쿼리
1 unique → 서로 다른 쿼리 패턴은 딱 1개뿐 (즉, 같은 쿼리가 반복 실행됨)
0.03 QPS → 초당 평균 0.03건 실행 (거의 1분에 2건 정도)
0.04x concurrency → 평균적으로 DB 연결 리소스를 점유한 수준이 낮음
실행 시간은 평균 1~2초
보내는 행은 200여 개뿐이지만
실제 스캔한 행은 80만 개 이상

필요한 결과는 200행인데, 백만 단위의 row를 뒤져서 찾고 있음 (인덱스 부재 가능성 높음)

문제 쿼리

SELECT new CounselorSearchResponseDto(...)
FROM Counselors c
LEFT JOIN Users u ON u.id = c.user_id
LEFT JOIN CounselorGrades cg ON cg.id = c.counselor_grade_id
LEFT JOIN CounselorFavorite f ON c.id = f.counselor_id AND f.user_id = :userId
LEFT JOIN CounselorBadge cb ON cb.counselor_id = c.id
WHERE c.status NOT IN ('inactive','terminated','unapproved')
  AND c.user_id NOT IN (
      SELECT ub.user_id 
      FROM UserBlock ub 
      WHERE ub.reporter_id = :userId 
        AND NOT (ub.is_deleted IS NULL OR ub.is_deleted = 1)
  )
ORDER BY c.sequence DESC;

여러 테이블 LEFT JOIN + 서브쿼리
Rows_examined가 80만인데, 실제 반환은 200행 → 인덱스 미사용
문자열 비교(availableStartTime, availableEndTime)로 인해 인덱스 사용 어려움
정렬(ORDER BY c.sequence) 포함 → 인덱스 없으면 느림

개선 포인트

인덱스 후보

-- Counselors 테이블
CREATE INDEX idx_c_status_user_sequence ON Counselors(status, user_id, sequence);

-- UserBlocks 테이블
CREATE INDEX idx_ub_reporter_user_deleted ON UserBlocks(reporter_id, user_id, is_deleted);

-- Reviews, ChatRooms
CREATE INDEX idx_reviews_counselor ON Reviews(counselor_id);
CREATE INDEX idx_chatrooms_counselor ON ChatRooms(counselor_id);

쿼리 구조 개선

서브쿼리 → JOIN + GROUP BY 변환 가능
문자열 비교 → 정규화된 숫자/시간 컬럼 사용

정리

slow_query_log 자체를 그대로 보는 건 의미가 없다.
쿼리 패턴별로 묶어서 집계해야 진짜 문제를 알 수 있다.
pt-query-digest를 활용하면 수만 건 로그도 단 몇 초 만에 정리 가능하다.
상위 몇 개의 문제 쿼리만 개선해도 전체 성능이 크게 개선된다.
이 결과는 "분석한 느린 쿼리 중 단 하나의 쿼리 패턴이 원인"임을 알 수 있다.
문제는 200여 건의 결과를 위해 매번 80만 row를 스캔하는 구조 → 인덱스 최적화 및 쿼리 리팩토링이 필요하다.

Spring Boot에서 Caffeine Cache 적용과 캐시 관리 API 구현하기

smink — Wed, 27 Aug 2025 14:32:49 +0900

문제 상황

우리 서비스에서는 메인 배너, 서브 배너, 카테고리 등과 같이 자주 변하지 않는 데이터를 계속해서 조회하는 문제가 있었습니다.

예를 들어, 메인 페이지에 들어올 때마다 DB에서 배너 정보를 매번 조회한다면,

불필요하게 DB 부하가 커지고,
트래픽이 많을 경우 성능 저하로 이어질 수 있습니다.

특히 배너나 카테고리처럼 한 번 가져오면 크게 변하지 않는 데이터를 매번 불러오는 건 낭비에 가까웠습니다.

Spring Boot + Caffeine Cache

해결 방법: 스프링부트 캐시 도입

이 문제를 해결하기 위해 선택한 방법은 Spring Boot의 캐시(Cache) 기능이었습니다.

스프링 캐시는 단순히 @Cacheable, @CacheEvict 등의 어노테이션만으로 손쉽게 적용할 수 있습니다.

@Cacheable → 캐시에 값이 없을 경우 메서드를 실행하고, 결과를 캐시에 저장
@CacheEvict → 특정 캐시를 비워서 새로운 값으로 다시 채울 수 있도록 만듦

이렇게 적용하면,
한 번 조회된 데이터는 캐시에 보관되고, 같은 요청이 들어와도 DB를 다시 조회하지 않고 캐시된 값을 반환할 수 있게 됩니다.

캐시 삭제 기능도 함께 구현한 이유

처음엔 @Cacheable만 적용했을 때는 성능이 확실히 좋아졌습니다.
하지만 문제는 데이터가 변경되었을 때였습니다.

예를 들어 관리자가 메인 배너를 교체했는데,
캐시에 기존 데이터가 남아있다면 유저는 새로운 배너를 볼 수 없습니다.

따라서, 필요할 때 캐시를 강제로 비워주는 기능이 필요했습니다.

이를 위해 캐시 삭제 API를 따로 만들었습니다.

코드 분석

1. 캐시 설정 (CacheConfig)

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public CacheManager cacheManager() {
        SimpleCacheManager cacheManager = new SimpleCacheManager();

        CaffeineCache mainBannersCache = new CaffeineCache("mainBanners",
                Caffeine.newBuilder()
                        .expireAfterWrite(5, TimeUnit.HOURS)
                        .maximumSize(5)
                        .build());

        CaffeineCache categoriesCache = new CaffeineCache("categories",
                Caffeine.newBuilder()
                        .expireAfterWrite(1, TimeUnit.DAYS)
                        .maximumSize(5)
                        .build());
                        
        CaffeineCache recommendCounselorsCache = new CaffeineCache("recommendCounselors",
                Caffeine.newBuilder()
                        .expireAfterWrite(60, TimeUnit.SECONDS) // 기본값 60s
                        .maximumSize(100) // 기본값 100
                        .build());

        // ... (다른 캐시 설정들 생략)

        cacheManager.setCaches(Arrays.asList(
                mainBannersCache,
                categoriesCache,
                recommendCounselorsCache,
                // ...
        ));

        return cacheManager;
    }
}

@EnableCaching : Spring 캐시 기능 활성화
CaffeineCache : 캐시 이름, 만료 시간(expireAfterWrite), 최대 크기(maximumSize) 지정
예시
- mainBanners → 5시간 동안 캐시 유지, 최대 5개 저장
- categories → 하루 동안 캐시 유지, 최대 5개 저장
- recommendCounselors → 60초 TTL, 최대 100개 저장

이렇게 캐시 특성에 맞게 데이터 성격별로 캐시 만료 정책을 다르게 설정했습니다.

2. 캐시 적용 (서비스 계층)

@Cacheable(value = "mainBanners")
public List<Banner> getMainBanners() {
    return bannerRepository.findMainBanners();
}

@Cacheable(value = "categories")
public List<Category> getCategories() {
    return categoryRepository.findAll();
}

// ... 나머지 생략

@Cacheable("캐시명") : 처음 호출 시 DB에서 가져와 캐시에 저장, 이후에는 캐시에서 반환
변경 주기가 긴 데이터(배너, 카테고리 등)에 적합

3. 캐시 삭제 기능

@Service
public class CacheService {

    private final CacheManager cacheManager;

    public CacheService(CacheManager cacheManager) {
        this.cacheManager = cacheManager;
    }

    // 특정 캐시 저장소의 모든 데이터를 삭제
    public void evictAllCacheValues(String cacheName) {
        Cache cache = cacheManager.getCache(cacheName);
        if (cache != null) {
            cache.clear();
        }
    }

    // 모든 캐시 저장소의 모든 데이터를 삭제
    public void evictAllCaches() {
        cacheManager.getCacheNames().stream()
                .forEach(cacheName -> evictAllCacheValues(cacheName));
    }

    // 모든 캐시 저장소 이름 조회
    public List<String> getAllCacheNames() {
        Collection<String> cacheNames = cacheManager.getCacheNames();
        return cacheNames.stream().collect(Collectors.toList());
    }
}

cacheManager.getCache(cacheName) : 캐시 이름으로 특정 캐시 가져오기
cache.clear() : 해당 캐시 전체 삭제

4. 캐시 삭제 API

@RestController
@RequestMapping("/cache")
public class CacheController {

    @Autowired
    private CacheService cacheService;

    // 모든 캐시를 삭제하는 API
    @DeleteMapping("/evict-all")
    public String evictAllCaches() {
        cacheService.evictAllCaches();
        return "All caches have been cleared.";
    }

    // 특정 캐시를 삭제하는 API
    @DeleteMapping("/evict/{cacheName}")
    public String evictSpecificCache(@PathVariable String cacheName) {
        cacheService.evictAllCacheValues(cacheName);
        return String.format("Cache '%s' has been cleared.", cacheName);
    }

    // 현재 존재하는 모든 캐시 이름 조회 API
    @GetMapping("/names")
    public List<String> getCacheNames() {
        return cacheService.getAllCacheNames();
    }
}

@DeleteMapping("/evict/{cacheName}") : REST API를 통해 특정 캐시 삭제 가능
사용 예: DELETE /cache/evict/mainBanner → 메인 배너 캐시만 삭제됨

결과 및 정리

이번 캐시 적용을 통해 다음과 같은 효과를 얻을 수 있었습니다.

DB 부하 감소 → 잦은 동일 조회가 캐시로 대체되어 DB 호출 횟수 절감
응답 속도 향상 → 캐시에서 바로 데이터를 꺼내오기 때문에 조회 속도가 빨라짐
운영 편의성 확보 → 캐시 삭제 API를 통해 수정된 데이터가 즉시 반영될 수 있음
데이터 특성에 맞는 TTL 설정 → 배너/카테고리/상담사 추천 등 데이터 성격별 만료 정책 적용
캐시 + 캐시 무효화 전략을 함께 가져감으로써, 성능 최적화와 데이터 일관성 두 마리 토끼를 잡을 수 있었음

Firebase Functions onWrite와 Too Many Connections 오류

smink — Mon, 28 Jul 2025 16:57:26 +0900

MySQL too many connections error

Firebase를 이용한 서비스에서 데이터베이스를 MySQL로 마이그레이션하는 과정은 효율적인 데이터 동기화가 핵심입니다. 특히 Firebase Functions의 onWrite 트리거를 사용하여 Firestore 데이터를 MySQL로 실시간 동기화할 때, 대규모 데이터 업데이트는 예상치 못한 Too Many Connections 오류를 유발할 수 있었습니다. 본 글에서는 마이그레이션 과정에서 겪었던 이러한 문제 상황과 그 해결 과정을 공유합니다.

문제 상황: 베스트 리뷰 선정과 대규모 onWrite 트리거

저희 서비스에는 특정 리뷰를 '베스트 리뷰'로 설정하는 기능이 있습니다. 이 기능은 다음과 같은 로직으로 작동하도록 설계되었습니다.

특정 리뷰를 베스트 리뷰로 설정하게되면 해당 리뷰의 today_index가 0으로 설정됩니다.
기존 베스트 리뷰들의 today_index 증가: 이전에 베스트 리뷰로 선정되었던 리뷰들의 today_index 값이 1씩 증가합니다.

문제는 이 과정에서 Firebase DB의 베스트 리뷰 관련 문서가 1,300개 이상 동시에 업데이트되었다는 점이었습니다. 저희는 Firebase Functions의 onWrite 트리거를 활용하여 Firestore의 모든 쓰기 작업을 감지하고 이를 MySQL 데이터베이스에 동기화하는 방식을 사용하고 있습니다.

하지만 1,300개가 넘는 문서가 동시에 업데이트되자, 1,300개 이상의 Firebase Functions 인스턴스가 동시에 실행되어 MySQL 데이터베이스에 연결을 시도하게 되었습니다. MySQL 서버는 동시에 수락할 수 있는 최대 연결 수(max_connections)가 제한되어 있는데, 이 한도를 초과하면서 Error: Too many connections 오류가 빈번하게 발생하기 시작했습니다.

이러한 오류는 데이터 동기화 실패뿐만 아니라, 데이터베이스 서버에 과도한 부하를 주어 서비스 전반의 안정성에도 부정적인 영향을 미쳤습니다.

해결 과정: Spring Server API를 통한 우회 적용

이 문제를 해결하기 위해 저는 다음과 같은 전략을 적용했습니다.

핵심: 베스트 리뷰 설정과 같이 대규모 onWrite를 유발하는 특정 기능에 대해서는 Firebase DB를 직접 수정하는 방식 대신, Spring Server API를 통해 MySQL 데이터를 직접 업데이트하도록 변경하는 방법을 택했습니다.

Firebase Functions onWrite 우회: '베스트 리뷰' 설정 시 Firebase Firestore의 리뷰 문서를 직접 업데이트하지 않도록 로직을 수정했습니다.
Spring Server API 호출: 대신, 클라이언트나 백엔드에서 Spring Server API를 호출하도록 변경했습니다.
MySQL 직접 업데이트: Spring Server API는 MySQL 데이터베이스에 직접 접근하여, 해당 리뷰의 today_index를 0으로 설정하고, 기존 베스트 리뷰들의 today_index를 1씩 증가시키는 작업을 수행하도록 구현했습니다.

이 방법이 효과적이었던 이유

커넥션 풀(Connection Pool) 활용: Spring Server는 일반적으로 JDBC 커넥션 풀(예: HikariCP)을 사용하여 데이터베이스 연결을 관리합니다. 커넥션 풀은 미리 정해진 수의 연결을 생성해두고 재사용하므로, 동시에 많은 요청이 들어와도 MySQL 서버에 대한 연결 수가 max_connections를 초과하지 않도록 효과적으로 제어할 수 있었습니다.
단일 작업으로 처리: Spring Server API 내부에서는 1,300개의 업데이트 작업을 하나의 트랜잭션 또는 효율적인 배치 쿼리로 처리할 수 있었습니다. 이는 Firebase Functions에서 1,300번의 개별 연결 및 트랜잭션을 시도하는 것보다 훨씬 효율적이었습니다.
서버리스 한계 극복: Firebase Functions는 강력하지만, 짧은 시간에 폭발적인 동시 실행이 필요한 대규모 배치 작업에는 Too Many Connections와 같은 리소스 한계에 직면할 수 있습니다. Spring Server와 같은 전통적인 백엔드 서버는 이러한 시나리오에 더 적합한 대안이 될 수 있었습니다.

결론

Firebase Functions의 onWrite 트리거는 실시간 데이터 동기화에 매우 유용하지만, 대규모 데이터 업데이트가 빈번하게 발생하는 특정 기능에 대해서는 Too Many Connections와 같은 문제를 야기할 수 있다는 점을 경험했습니다. 이러한 경우에는 애플리케이션의 특정 로직을 백엔드 서버(예: Spring Server)로 분리하고, 해당 서버에서 데이터베이스 커넥션 풀과 효율적인 쿼리 방식을 활용하여 MySQL을 직접 업데이트하는 전략이 효과적인 해결책이 될 수 있음을 확인했습니다.

이 과정은 시스템의 안정성을 확보하고, 각 기술 스택의 장점을 최대한 활용하는 중요한 경험이 되었습니다.

AWS EC2 인스턴스 용량 확장 및 추가 Swap Memory 설정

smink — Tue, 22 Jul 2025 11:00:07 +0900

제가 운영 중인 AWS EC2 인스턴스는 메모리와 디스크 상황이 다음과 같습니다.

df -h
/dev/root        30G   25G  4.8G  84% /

free -h
              total        used        free      shared  buff/cache   available
Mem:          3.8Gi       3.0Gi       127Mi       9.0Mi       705Mi       557Mi
Swap:         2.0Gi       2.0Gi        40Mi

디스크 사용량: 30GB 중 25GB 사용 (84%) → 여유가 크진 않음
메모리: 3.8GiB 중 3.0GiB 사용, swap 2GiB 거의 다 사용 중
사용 가능한 메모리: 557Mi 정도로 매우 낮은 상황

이런 상황에서 안정적인 서비스 운영을 위해서:

EC2 인스턴스의 EBS 볼륨 용량을 30GB → 100GB로 늘려 디스크 공간을 확보하고,
OOM(Out of Memory) 방지를 위해 기존 스왑 메모리 외에 추가적인 스왑 메모리를 설정하기로 결정했습니다.

1️⃣ EC2 EBS Volume 크기 확장하기

AWS EC2 인스턴스를 사용하다 보면 디스크 용량 부족 문제가 자주 발생합니다.
다행히 AWS에서는 EC2 중단 없이 디스크(EBS 볼륨) 크기를 늘릴 수 있어요!

✅ 1단계 : 현재 디스크 상태 확인

SSH로 EC2에 접속해서 다음 명령어로 현재 디스크 정보를 확인합니다.

df -h

df -h

/dev/root 또는 /dev/xvda1 같이 표시되는 루트 디스크가 주로 대상입니다.

✅ 2단계 : AWS 콘솔에서 EBS 볼륨 크기 변경

1️⃣ AWS Management Console 접속

2️⃣ EC2 > Elastic Block Store > Volumes 메뉴 클릭

EC2_EBS_volumn

3️⃣ 대상 볼륨 선택 (인스턴스와 연결된 볼륨)

4️⃣ 볼륨 > 우측 상단 수정 버튼 클릭

볼륨

5️⃣ 새로운 크기 입력 (예: 기존 30GiB → 100GiB)

볼륨 수정

원하는 크기로 수정 후 오른쪽 하단 '수정' 버튼 클릭

볼륨을 수정하시겠습니까?

이 작업은 인스턴스 중단 없이 즉시 적용됩니다.
일정 시간 이후 볼륨이 수정된 것을 확인할 수 있습니다.

✅ 3단계 : EC2 인스턴스 안에서 파일 시스템 확장

AWS 콘솔에서 크기를 늘리면, EC2 OS에서는 파일 시스템 확장을 해줘야 실제 사용이 가능합니다.

파일 시스템 종류에 따라 다르게 진행합니다.

df -T 명령어 또는 lsblk -f 명령어를 사용하여 파일 시스템 타입을 바로 확인할 수 있습니다.

df -T를 사용한 파일 시스템 타입 확인

ext4 파일 시스템

# growpart를 이용해 파티션 확장
sudo growpart /dev/xvda 1

# 파일 시스템 확장
sudo resize2fs /dev/xvda1

xfs 파일 시스템

sudo xfs_growfs /

대부분 Amazon Linux 2나 최근 Ubuntu에서는 /가 /dev/xvda1 또는 /dev/nvme0n1p1로 잡혀있습니다.
정확한 디바이스 이름은 lsblk로 확인 가능

✅ 4단계 : 최종 확인

df -h

df -h 최종 확인

확장된 디스크 용량이 정상적으로 반영됐는지 확인합니다.

2️⃣ 추가 스왑 메모리(Swap Memory) 설정하기

이미 EC2에 스왑 메모리가 설정되어 있지만,
메모리가 부족하다면 추가적인 스왑 파일을 설정해서 Out of Memory(OOM) 상황을 방지할 수 있습니다.

✅ 1단계 : 기존 스왑 확인

free -h

# 또는

swapon --show

# 기존에 설정된 스왑 파일이 보입니다.

free -h

✅ 2단계 : 추가 스왑 파일 생성

저는 4GiB 스왑 파일을 추가로 설정해 보겠습니다.

# 스왑 파일 생성
sudo fallocate -l 4G /swapfile2

# 권한 설정
sudo chmod 600 /swapfile2

# 스왑 영역으로 설정
sudo mkswap /swapfile2

# 스왑 활성화
sudo swapon /swapfile2

✅ 3단계 : 영구 적용

인스턴스를 재부팅해도 자동으로 적용되도록 /etc/fstab에 추가합니다.

echo '/swapfile2 none swap sw 0 0' | sudo tee -a /etc/fstab

✅ 4단계 : 최종 확인

free -h

추가된 스왑 메모리가 합산되어 표시됩니다.

추가 스왑파일 설정 후 free -h

결과

이번 글에서는 현재 EC2 인스턴스의 메모리와 디스크 상황이 여유가 거의 없는 상태여서

EBS 볼륨 용량을 늘려 디스크 공간을 확보하고,
추가 스왑 메모리를 설정해 OOM(Out of Memory) 상황을 예방하는 방법을 정리해봤습니다.

EBS 볼륨 증설은 인스턴스 중단 없이 진행할 수 있어 편리하지만,
스왑 메모리는 임시방편일 뿐, 과도하게 사용하면 성능 저하가 생길 수 있으니 주의가 필요합니다.

장기적으로는 인스턴스 타입 업그레이드나 메모리 최적화 등도 함께 검토하는 것이 좋겠습니다.

JMeter를 이용한 Spring Boot API 부하 테스트

smink — Tue, 13 May 2025 10:52:13 +0900

1️⃣ JMeter 설치

JMeter

JMeter 최신 버전 다운로드
https://jmeter.apache.org/download_jmeter.cgi

Apache JMeter - Download Apache JMeter

Download Apache JMeter We recommend you use a mirror to download our release builds, but you must verify the integrity of the downloaded files using signatures downloaded from our main distribution directories. Recent releases (48 hours) may not yet be ava

jmeter.apache.org

압축 해제 후 bin/jmeter.bat (Windows) 또는 bin/jmeter (Mac/Linux) 실행

JMeter 실행 실패시

✅ 해결 방법 (macOS에서 JMeter 실행 허용)

1️⃣ 보안 설정에서 수동 허용

JMeter 실행을 시도한 후, 위와 같은 경고가 뜨면 "취소" 를 클릭합니다.
상단 메뉴에서 Apple 로고 > 시스템 설정(또는 환경설정) > 개인정보 보호 및 보안 > "앱 실행 허용" 섹션으로 이동합니다.
"jmeter was blocked…" 경고 메시지가 보이면 "그래도 열기" 버튼을 클릭합니다.
다시 실행하면 한 번만 확인 창이 나오고 이후로는 실행됩니다.

2️⃣ 터미널 명령어로 강제 허용 (보안 해제)

bash

복사편집

xattr -d com.apple.quarantine /path/to/jmeter/bin/jmeter

예를 들어, JMeter가 ~/Downloads/apache-jmeter-5.6.3/에 있다면:

bash

복사편집

xattr -d com.apple.quarantine ~/Downloads/apache-jmeter-5.6.3/bin/jmeter

그 후 다시 실행:

bash

복사편집

cd ~/Downloads/apache-jmeter-5.6.3/bin ./jmeter

참고

위 방법은 공식 JMeter를 apache.org에서 직접 다운로드했을 경우에만 안전합니다.
GitHub 등에서 받은 미확인 JMeter 패키지에는 악성코드 위험이 있을 수 있으니 출처 확인 필수입니다.

2️⃣ 테스트 플랜 구성 (GUI)

(1) Test Plan 생성

Test Plan → 우클릭 → Add → Threads (Users) → Thread Group

Test Plan 생성

(2) Thread Group 설정

Number of Threads (users): 200 (사용자 수)
Ramp-Up Period (seconds): 5 (사용자 200명을 5초에 걸쳐 증가)
Loop Count: 50 (각 사용자당 요청 횟수)

Thread Group 설정

(3) HTTP Request 샘플러 추가

Thread Group → 우클릭 → Add → Sampler → HTTP Request
Method: GET 또는 POST (API에 맞게 선택)
Server Name or IP: api.example.com (또는 EC2 IP/domain)
Path: /api/posts 등
Body Data: POST일 경우 JSON 본문 입력
Content encoding : application/json

(4) 헤더 추가 (필요시)

Thread Group → 우클릭 → Config Element → HTTP Header Manager
Content-Type: application/json Authorization: Bearer <토큰>

(5) View Results Tree 추가 (디버깅용)

Thread Group → 우클릭 → Listener → View Results Tree

View Results Tree

(6) 요약 리포트 추가

Listener → Summary Report / Aggregate Report 추가

Summary Report / Aggregate Report 추가

3️⃣ 테스트 실행 및 결과 확인

▶️ 버튼 클릭 → 테스트 실행

▶️ 버튼 클릭 → 테스트 실행

결과:
- Throughput: 초당 처리량
- Average: 평균 응답 시간
- Error %: 오류 발생률
- Latency / Min / Max: 지연시간 지표
- 90% Line: 사용자의 90%가 느끼는 응답속도, SLA 기준으로 자주 사용됨

4️⃣ 테스트 파일 저장 및 CLI 실행

GUI 설정이 끝나면 .jmx 파일로 저장할 수 있고, 아래처럼 CLI에서도 실행할 수 있습니다:

jmeter -n -t test-plan.jmx -l result.jtl -e -o report

-n: GUI 없이 실행
-t: 테스트 플랜 파일
-l: 결과 저장
-e -o: HTML 리포트 생성

✅ 팁

테스트 중 k3s의 kubectl top pods 명령어로 CPU, 메모리 리소스도 함께 관찰하세요.
EC2에서 JMeter를 실행할 경우, 애플리케이션 서버와 다른 인스턴스를 사용하는 것이 정확한 측정을 위한 이상적 환경입니다.
부하 테스트 결과와 함께 GC 로그, 애플리케이션 로그, Spring Boot actuator metrics도 확인하면 좋습니다.

GitHub Actions를 이용한 Vue 프로젝트 Firebase Hosting 자동 배포

smink — Fri, 2 May 2025 16:48:03 +0900

GitHub Actions를 이용한 Vue 프로젝트 Firebase Hosting 자동 배포

firebase hosting

개요

이 글에서는 GitHub Actions를 활용하여 main 브랜치에 코드를 push하면 자동으로 Vue 프로젝트가 Firebase Hosting에 배포되도록 구성하는 방법을 설명합니다. CI/CD를 통해 반복적인 배포 작업을 자동화하고, 안정적인 배포 흐름을 구축할 수 있습니다.

workflow/firebase-hosting.yaml

name: Deploy to Firebase Hosting

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout source
      uses: actions/checkout@v3

    - name: Install Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '21.5.0'  # 프로젝트 Node 버전에 맞게 수정

    - name: Install and Build admin app
      working-directory: firebase/admin
      run: |
        npm install
        npm run build

    - name: Write Firebase service account key
      run: |
        echo '${{ secrets.GOOGLE_APPLICATION_CREDENTIALS_JSON }}' > ${HOME}/firebase-key.json
        echo "GOOGLE_APPLICATION_CREDENTIALS=${HOME}/firebase-key.json" >> $GITHUB_ENV

    - name: Deploy to Firebase Hosting (admin)
      working-directory: firebase
      run: |
        npm install -g firebase-tools
        firebase deploy --only hosting:admin

1. Workflow 개요

name: Deploy to Firebase Hosting

on:
  push:
    branches:
      - main

동작 조건: main 브랜치에 push가 발생하면 워크플로우가 실행됩니다.
목표: firebase/admin 디렉토리의 Vue 앱을 빌드하고, hosting:admin으로 Firebase에 배포합니다.

2. Job 정의 및 빌드 환경 설정

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

GitHub Actions의 Ubuntu 최신 버전 환경에서 Job이 실행됩니다.
단일 Job(build-and-deploy) 내에서 모든 빌드 및 배포가 처리됩니다.

3. Step별 설명

Github Secrets
GitHub 저장소의 Secrets에 아래 항목을 추가해야 합니다:

GOOGLE_APPLICATION_CREDENTIALS_JSON
- Firebase 서비스 계정 JSON 전체를 문자열로 복사해 저장
- Firebase 콘솔 > 프로젝트 설정 > 서비스 계정 > 새 비공개 키 발급

✅ 소스코드 체크아웃

- name: Checkout source
  uses: actions/checkout@v3

현재 리포지토리의 코드를 GitHub Actions 실행 환경으로 가져옵니다.

Node.js 설치

- name: Install Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '21.5.0'

해당 Node 버전(21.5.0)으로 설정합니다. 프로젝트에 맞는 버전으로 변경해야 합니다.

️ Vue 프로젝트 설치 및 빌드

- name: Install and Build admin app
  working-directory: firebase/admin
  run: |
    npm install
    npm run build

firebase/admin 경로에서 Vue 앱을 설치(npm install)하고 빌드(npm run build)합니다.
이때 dist 폴더가 생성되고, 해당 폴더가 Firebase Hosting에 배포됩니다.

Firebase 인증 키 작성

- name: Write Firebase service account key
  run: |
    echo '${{ secrets.GOOGLE_APPLICATION_CREDENTIALS_JSON }}' > ${HOME}/firebase-key.json
    echo "GOOGLE_APPLICATION_CREDENTIALS=${HOME}/firebase-key.json" >> $GITHUB_ENV

GitHub Secrets에 저장된 Firebase 서비스 계정 키 JSON을 파일로 저장하고, 환경변수로 등록합니다.
환경변수 GOOGLE_APPLICATION_CREDENTIALS에 해당 키 파일 경로를 설정하여 Firebase CLI에서 인증에 사용할 수 있게 합니다.

Firebase Hosting 배포

- name: Deploy to Firebase Hosting (admin)
  working-directory: firebase
  run: |
    npm install -g firebase-tools
    firebase deploy --only hosting:admin

Firebase CLI를 설치하고, hosting:admin에만 배포를 실행합니다.
Firebase 프로젝트 설정의 firebase.json에서 hosting에 target: "admin" 설정이 되어 있어야 합니다.

4. Firebase Hosting 타겟 설정 예시

firebase.json 예시:

{
  "hosting": [
    {
      "target": "admin",
      "public": "admin/dist",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"]
    }
  ]
}

.firebaserc 예시:

{
  "projects": {
    "default": "your-firebase-project-id"
  },
  "targets": {
    "your-firebase-project-id": {
      "hosting": {
        "admin": ["your-site-id"]
      }
    }
  }
}

마무리

이제 main 브랜치에 코드를 push하면 GitHub Actions가 자동으로 Vue 앱을 빌드하고 Firebase에 배포합니다.

이를 통해 반복적인 개발-테스트-배포 과정을 수동으로 작업하지 않고, 빠르고 안정적인 배포 환경을 구축할 수 있습니다.

Spring Boot CI/CD with Github Actions, ECR, Docker, K3S

smink — Thu, 24 Apr 2025 11:53:25 +0900

Spring Boot CI/CD with Github Actions, ECR, Docker, K3s

Github Actions를 사용하여 Spring Boot 프로젝트를 AWS EC2 환경에 자동 배포하는 CI/CD 파이프라인을 구축하는 과정을 작성해보겠습니다. ECR(Elastic Container Registry)을 이용하여 Docker 이미지를 관리하고, 경량 Kubernetes 배포판인 K3s를 통해 EC2 인스턴스에서 Spring Boot 애플리케이션을 컨테이너화하여 배포합니다. 전체 배포 과정은 Github main 브랜치에 코드가 병합되는 것을 트리거로 하여 자동으로 진행됩니다.

CICD_Architecture

간략한 계획은 다음과 같습니다.

Github main branch merge: 코드 변경 사항이 main 브랜치에 병합되면 CI/CD 파이프라인이 시작됩니다.
./gradlew clean build: Spring Boot 프로젝트를 Gradle을 사용하여 빌드합니다.
docker build -t springBootPJT .: Docker 이미지를 빌드합니다.
AWS ECR로 푸시하기: 빌드된 Docker 이미지를 AWS ECR 리포지토리에 푸시합니다.
ssh 를 통해 EC2에 접속하기: Github Actions Runner에서 SSH를 통해 EC2 인스턴스에 접속합니다.
K3s를 통해 프로젝트 배포하기: EC2 인스턴스에서 kubectl 명령어를 사용하여 Kubernetes 매니페스트 파일들을 적용하고 Spring Boot 애플리케이션을 배포합니다.

Github Actions

name: Spring Boot CI/CD

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: Grant execute permission for gradlew
      run: chmod +x gradlew

    - name: Build with Gradle
      run: ./gradlew clean build -x test

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ secrets.AWS_REGION }}

    - name: Login to Amazon ECR
      id: login-ecr
      uses: aws-actions/amazon-ecr-login@v2

    - name: Build and push Docker image
      env:
        ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        ECR_REPOSITORY: ${{ secrets.ECR_REPOSITORY_NAME }}
        IMAGE_TAG: ${{ github.sha }}
      run: |
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

    - name: Copy Kubernetes manifests to EC2
      uses: appleboy/scp-action@v0.1.7
      with:
        host: ${{ secrets.EC2_HOST }}
        username: ${{ secrets.EC2_USERNAME }}
        key: ${{ secrets.EC2_PRIVATE_KEY }}
        port: ${{ secrets.EC2_PORT }}
        source: "./spring-deployment.yaml, ./spring-service.yaml"
        target: user_path # 경로 변경!

    - name: SSH to EC2 and deploy to K3s
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.EC2_HOST }}
        username: ${{ secrets.EC2_USERNAME }}
        key: ${{ secrets.EC2_PRIVATE_KEY }}
        port: ${{ secrets.EC2_PORT }}
        script: |
          echo "Logging in to EC2..."

          ECR_REGISTRY="${{ steps.login-ecr.outputs.registry }}"
          AWS_ACCESS_KEY_ID="${{ secrets.AWS_ACCESS_KEY_ID }}"
          IMAGE_FULL="${ECR_REGISTRY}/${{ secrets.ECR_REPOSITORY_NAME }}:${{ github.sha }}"
          
          # Docker Registry 인증 정보를 담는 Kubernetes Secret 생성 또는 업데이트
          aws ecr get-login-password --region ap-northeast-2 | docker login --username AWS --password-stdin $ECR_REGISTRY
          sudo kubectl --kubeconfig=/etc/rancher/k3s/k3s.yaml create secret generic regcred \
            --from-file=.dockerconfigjson=/home/ubuntu/.docker/config.json \
            --type=kubernetes.io/dockerconfigjson \
            --namespace=default \
            --dry-run=client -o yaml | sudo kubectl --kubeconfig=/etc/rancher/k3s/k3s.yaml apply -f -

          # deployment.yaml 파일 내용 변경 (이미지 업데이트)
          sudo sed -i "s|image: REPLACE_IMAGE|image: $IMAGE_FULL|g" user_path/spring-deployment.yaml # 경로 변경!

          echo "Applying Kubernetes manifest..."
          sudo kubectl apply -f user_path/spring-deployment.yaml # 경로 변경!
          sudo kubectl apply -f user_path/spring-service.yaml # 경로 변경!
          echo "Deployment completed!"

Github Secrets 환경 변수

Github Repository의 "Settings" -> "Secrets and variables" -> "Actions" -> "New repository secret" 메뉴를 통해 다음 환경 변수들을 등록해야 합니다.

AWS_ACCESS_KEY_ID: AWS Access Key ID
AWS_SECRET_ACCESS_KEY: AWS Secret Access Key
AWS_REGION: AWS Region (예: ap-northeast-2)
ECR_REPOSITORY_NAME: ECR 리포지토리 이름
EC2_HOST: EC2 인스턴스의 IP 주소 또는 도메인
EC2_USERNAME: EC2 접속 사용자 이름 (예: ec2-user, ubuntu)
EC2_PRIVATE_KEY: EC2 접속을 위한 SSH Private Key (주의: 보안에 매우 중요!)
EC2_PORT: SSH 포트 (기본값은 22)

Dockerfile

FROM openjdk:17-jdk

CMD ["./gradlew", "clean", "build"]

COPY build/libs/*SNAPSHOT.jar app.jar

EXPOSE 8080

ENTRYPOINT ["java", "-jar", "/app.jar"]

spring-deployment.yaml (K3s deployment)

Github Repository의 디렉토리에 위치해야 하며, 내용은 다음과 같습니다.

YAML

apiVersion: apps/v1
kind: Deployment

metadata:
  name: spring-deployment

# Deployment 세부 정보
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend-app

  # 배포할 Pod 정의
  template:
    metadata:
      labels:
        app: backend-app
    spec:
      imagePullSecrets:
        - name: regcred
      containers:
        - name: spring-container
          image: REPLACE_IMAGE
          ports:
            - containerPort: 8080
          env:
            - name: MYSQL_URL
              valueFrom:
                secretKeyRef:
                  key: mysql-url
                  name: spring-secret
            - name: MYSQL_USERNAME
              valueFrom:
                secretKeyRef:
                  key: mysql-username
                  name: spring-secret
            - name: MYSQL_PASSWORD
              valueFrom:
                secretKeyRef:
                  key: mysql-password
                  name: spring-secret

spring-service.yaml (K3s Service)

EC2 인스턴스에 K3s 클러스터 내에 이미 다음과 같은 Service가 존재해야 합니다.

YAML

apiVersion: v1
kind: Service

# Service 기본 정보
metadata:
  name: spring-service # Service 이름

# Service 세부 정보
spec:
  type: NodePort # Service의 종류
  selector:
    app: backend-app # 실행되고 있는 파드 중 'app: backend-app' 이라는 값을 가진 파드와 서비스를 연결
  ports:
    - protocol: TCP # Service에 접속하기 위한 프로토콜
      port: 8080 # 쿠버네티스 내부에서 Service에 접속하기 위한 포트 번호
      targetPort: 8080 # 매핑하기 위한 파드의 포트 번호
      nodePort: 30000 # 외부에서 사용자들이 접근하게 될 포트 번호
      # The Service "spring-service" is invalid: spec.ports[0].nodePort: Invalid value: 8080: provided port is not in the valid range. The range of valid ports is 30000-32767
      # nodePort는 30000-32767 이내의 포트를 사용해야함

spring-secret.yaml (K3s Secret)

EC2 인스턴스에 K3s 클러스터 내에 이미 다음과 같은 Secret이 존재해야 합니다.

YAML

apiVersion: v1
kind: Secret

# Secret 기본 정보
metadata:
  name: spring-secret

# Key, Value 형식으로 설정값 저장
stringData:
  mysql-url: user_MySQL_url
  mysql-username: username
  mysql-password: myPassword123

추가 설명

이 워크플로우는 Spring Boot 프로젝트의 CI/CD 파이프라인을 자동화하여 개발자가 코드를 main 브랜치에 푸시하는 것만으로 EC2 인스턴스에 최신 버전의 애플리케이션을 배포할 수 있도록 구성되었습니다.

Workflow:
- main 브랜치에 푸시되면 자동으로 실행됩니다.
- Java 17 환경을 설정하고 Gradle을 사용하여 Spring Boot 프로젝트를 빌드합니다.
- AWS 인증 정보를 설정하고 ECR에 로그인하여 Docker 이미지를 빌드하고 푸시합니다. 이미지 태그는 Git 커밋 SHA를 사용합니다.
- SSH를 통해 EC2 인스턴스에 접속하여 Kubernetes Secret (regcred)을 생성/업데이트하여 ECR로부터 이미지를 pull 할 수 있도록 인증합니다.
- EC2 인스턴스에 Kubernetes Deployment (spring-deployment.yaml) 및 Service (spring-service.yaml) 매니페스트 파일을 복사하고, sed 명령어를 사용하여 Deployment의 이미지 이름을 최신 이미지 URI로 업데이트합니다.
- kubectl apply 명령어를 사용하여 Kubernetes 매니페스트 파일들을 K3s 클러스터에 적용하여 Spring Boot 애플리케이션을 배포합니다.
Github Secrets: 워크플로우에서 AWS 및 EC2 접근 정보를 안전하게 관리하기 위해 Github Secrets를 사용합니다.
spring-deployment.yaml: Spring Boot 애플리케이션 파드를 관리하는 Kubernetes Deployment 설정 파일입니다. 레포지토리에는 이미지 업데이트를 위한 플레이스홀더(REPLACE_IMAGE)가 포함되어 있으며, 워크플로우 실행 중 실제 이미지 URI로 변경됩니다.
spring-service.yaml: Spring Boot 애플리케이션을 외부로 노출하는 Kubernetes Service 설정 파일입니다. NodePort 타입을 사용하여 특정 포트(30000)를 통해 접근할 수 있도록 구성되어 있습니다. 주의: nodePort는 유효한 범위(30000-32767) 내의 포트를 사용해야 합니다.
spring-secret.yaml: Spring Boot 애플리케이션이 사용할 MySQL 연결 정보를 담고 있는 Kubernetes Secret 설정 파일입니다. K3s 클러스터에 미리 존재해야 합니다.

이 설정을 통해 Github Actions 파이프라인은 main 브랜치에 코드가 푸시될 때 자동으로 빌드, Docker 이미지 푸시, EC2 인스턴스에 배포까지의 전체 과정을 자동화합니다.

Docker-hub, AWS ECR 비교하기

smink — Wed, 16 Apr 2025 12:28:04 +0900

개요

현재는 GitHub Actions를 통해 main 브랜치에 merge되었을 때, EC2 인스턴스에 작성해 둔 Shell Script를 실행하여 Spring Boot API 서버를 배포하고 있습니다.

이러한 방식은 간단하게 배포를 자동화할 수 있다는 장점이 있지만, 다음과 같은 문제점이 있었습니다.

기존 배포 방식의 문제점

무중단 배포의 어려움
서버를 중지하고 다시 시작하는 방식이기 때문에, 배포 시 사용자에게 순간적인 장애가 발생할 수 있습니다.
롤백의 어려움
문제가 생겼을 때 이전 버전으로 되돌리는 과정이 수동적이고 번거롭습니다.
트래픽 증가 대응의 어려움
EC2 인스턴스 하나에서 모든 요청을 처리하기 때문에, 트래픽이 늘어날 경우 확장이 어렵습니다.
환경 간 일관성 부족
로컬과 운영 환경의 설정 차이로 인해 예기치 못한 문제가 발생할 수 있습니다.

Docker & Kubernetes 도입 이유

이러한 문제점을 해결하기 위해 Docker와 Kubernetes 도입을 검토하게 되었습니다.

Docker는 이미지 기반의 배포 방식으로, 애플리케이션을 환경에 구애받지 않고 실행할 수 있습니다. 버전 태그를 통해 빠른 롤백이 가능하고, 동일한 환경 구성을 보장합니다.
Kubernetes(K8s)는 Rolling Update, Blue-Green Deployment 등의 배포 전략을 통해 무중단 배포를 지원하며, HPA(Horizontal Pod Autoscaler)를 통해 자동 스케일링도 가능합니다. 또한, Pod 상태를 지속적으로 체크하여 문제가 발생한 경우 자동으로 재시작하거나 교체하여 모니터링 및 장애 대응도 용이합니다.

이미지 저장소 선택: Docker Hub vs AWS ECR

오늘은 Spring Boot 프로젝트의 Docker 이미지를 생성한 후, 해당 이미지를 저장하고 배포할 저장소로 Docker Hub와 AWS ECR 중 어떤 것을 선택하는 것이 좋을지에 대해 정리해보려 합니다.

Docker Hub vs AWS ECR 비교

항목	Docker Hub	AWS ECR
설정 난이도	설정이 간단하고 직관적이며, CI/CD 연동도 쉬움	IAM 설정, 권한 부여 등 약간의 사전 설정이 필요함
속도 및 접근성	퍼블릭 레지스트리로 글로벌 CDN을 통해 빠른 이미지 접근 가능	같은 리전에 있을 경우 빠른 이미지 Pull이 가능함 (특히 AWS 서비스와 통합 시 강점)
보안	퍼블릭 기본, Private는 유료 제한 있음 (무료 계정은 private repo 수 제한)	기본적으로 private, IAM과 연계된 세밀한 권한 설정 가능
비용	퍼블릭은 무료, Private 저장소는 제한적 무료 또는 유료	AWS 프리 티어 제공, 사용량 초과 시 S3 기반 과금 발생
CI/CD 연동	GitHub Actions 등 외부 도구와 쉽게 연동 가능	GitHub Actions 또는 CodePipeline 등 AWS 생태계 연동이 뛰어남
사용성	전 세계적으로 널리 쓰이며 커뮤니티 및 문서가 풍부	AWS를 기반으로 하는 환경에 최적화되어 있음

Docker-hub

클라우드 기반 레포지토리.

도커 유저들은 도커 허브를 통해 컨테이너 이미지를 생성, 테스트, 저장 그리고 배포할 수 있습니다.

장점

간편한 사용: Docker 명령어로 간단히 이미지를 푸시하고 풀(pull)할 수 있어 사용이 매우 직관적이고 쉽습니다.
무료 사용: 개인용 공개 저장소는 무료로 제공되며, 기본적인 기능은 무료로 이용할 수 있습니다.
광범위한 지원: Docker와의 자연스러운 호환성으로, 다양한 Docker화된 애플리케이션을 쉽게 사용할 수 있습니다.

단점

속도: 글로벌 서버에 있는 Docker Hub의 이미지를 풀하는 속도가 지역에 따라 느릴 수 있습니다.
제한된 개인 저장소: 무료 계정에서는 개인 저장소의 수나 푸시 횟수 등에 제한이 있습니다.
보안 문제: 공개 저장소의 이미지는 누구나 접근할 수 있어, 보안 취약점이 있는 이미지를 사용할 위험이 있습니다.
비용: 개인 저장소의 수나 프라이빗 저장소 기능을 확장하려면 유료 플랜을 이용해야 하며, 비용이 발생합니다.
권한 관리: 권한 관리를 체계적으로 하지 못합니다.
클라우드 서비스로 AWS를 사용하지만, 컨테이너 이미지 관리는 도커 허브에서 하기 때문에 사용자가 관리해야 하는 서비스가 많습니다.

AWS ECR

안전하고 확장 가능하고 신뢰할 수 있는 AWS 관리형 컨테이너 이미지 레지스트리 서비스입니다.
AWS IAM을 사용하여 리소스 기반 권한을 가진 프라이빗 레포지토리를 지원합니다.
컨테이너 이미지를 Amazon S3에 저장합니다.

장점

AWS와의 통합: AWS의 다른 서비스들(예: ECS, EKS, Lambda)과 매끄럽게 통합되어, 관리가 용이하고 배포가 간편합니다.
보안: IAM(Identity and Access Management)을 사용해 사용자 및 권한 관리를 할 수 있어 보안이 강화됩니다. 이미지의 보안도 Amazon GuardDuty나 ECR Repository 정책을 통해 관리 가능합니다.
고가용성: AWS의 글로벌 인프라에 의해 높은 가용성과 안정성을 보장합니다.
자동화: ECR과 연동된 CI/CD 파이프라인을 쉽게 구성할 수 있어 자동화가 가능합니다.
클라우드 관리 용이성 : 클라우드 서비스를 이용하는 AWS에서 컨테이너 관리도 함께 하기 때문에 사용자가 관리하는 서비스가 적습니다.
컨테이너 관리 용이성 : S3를 이용하여 컨테이너를 쉽게 관리할 수 있습니다.

단점

비용: 저장 용량과 데이터 전송에 따른 요금이 부과됨. 사용량에 따라 가격이 올라갈 수 있어 비용 관리를 철저히 해야 합니다.
AWS 종속성: AWS 생태계에 종속되므로, AWS 밖의 환경에서 사용하기 어려운 점이 다소 존재합니다.
복잡한 설정: AWS의 복잡한 설정과 구성이 초보자에게는 다소 어려울 수 있습니다.

비용

AWS ECR (Amazon Elastic Container Registry)

1. 스토리지 비용

요금: $0.10/GB/월
예시: 1GB 이미지 저장 시 월 $0.10

2. 데이터 수신 비용 (Push)

요금: 무료

3. 데이터 송신 비용 (Pull)

동일 리전 내 EC2, ECS, Fargate 등에서 Pull 시: 무료
인터넷 또는 다른 리전으로의 Pull 시: $0.09/GB

4. 예상 비용 (월간)

스토리지: 1GB × $0.10 = $0.10
데이터 송신: 동일 리전 내에서 Pull 시 무료
총합: 약 $0.10/월

Docker Hub

1. 스토리지 비용

무료 플랜: 1개의 개인(private) 저장소, 최대 2GB 저장 용량
Pro 플랜: $9/월, 무제한 개인 저장소 및 추가 기능 제공

2. 데이터 수신 비용 (Push)

요금: 무료

3. 데이터 송신 비용 (Pull)

무료 플랜: 인증된 사용자 기준 6시간당 100회 Pull 제한
Pro 플랜 이상: Pull 횟수 무제한

4. 예상 비용 (월간)

무료 플랜: Pull 제한으로 인해 주 50회 이상 사용 시 제한에 걸릴 수 있음
Pro 플랜: $9/월

비교 요약

항목	AWS ECR	Docker Hub (Pro 플랜)
스토리지 요금	$0.10/GB/월	$9/월 (2GB 포함)
Push 요금	무료	무료
Pull 요금	동일 리전 내 무료	무제한 (Pro 플랜 기준)
Pull 제한	없음	무료 플랜은 제한 있음
총 예상 비용	약 $0.10/월 (1GB 기준)	$9/월

결론

기업 환경에서 EC2, RDS 등 AWS 인프라를 이미 사용 중이기 때문에 AWS ECR(Amazon Elastic Container Registry)는 다음과 같은 이유로 가장 적합하다고 생각하였습니다.

AWS 서비스와의 강력한 통합성
ECR은 EC2, ECS, Fargate, CodePipeline, IAM 등 다양한 AWS 서비스와 자연스럽게 연동되므로, 별도 설정 없이도 이미지 빌드부터 배포까지의 전체 워크플로우를 AWS 내에서 통합적으로 구성할 수 있습니다. 이는 유지보수 및 관리 효율성을 크게 높여줍니다.
리전 내 데이터 송수신 무료 혜택
동일 리전 내에서 EC2나 ECS와 같은 AWS 서비스가 ECR에서 이미지를 Pull 할 경우, 네트워크 요금이 발생하지 않기 때문에 운영 비용을 절감할 수 있습니다. 외부 레지스트리(Docker Hub 등)에서 이미지를 Pull 하면 인터넷 송신 요금이 발생할 수 있어 장기적으로는 비용 부담이 커질 수 있습니다.
보안 및 접근 제어
ECR은 AWS IAM과 연동되어, 세부적인 권한 관리(예: 특정 사용자에게만 Push 권한 부여 등)가 가능합니다. 또한, 이미지 스캔 기능을 통해 취약점 분석을 수행할 수 있어 보안이 중요한 기업 환경에 매우 적합합니다.
CI/CD 자동화에 최적화
AWS CodeBuild, CodePipeline과의 연계를 통해 자동 빌드 및 배포 파이프라인을 쉽게 구성할 수 있어 DevOps 환경에 최적화되어 있습니다.
하지만 Github Actions를 통한 CI/CD를 고려하고 있기 때문에 해당 항목은 크게 고려되지 않았습니다.
예상 가능하고 합리적인 비용
Docker Hub는 일정 횟수 이상 이미지 Pull이 발생하면 Pro 요금제 이상의 유료 플랜을 이용해야 하며, 일부 기업 환경에서는 비용이 예측 불가능하게 증가할 수 있습니다. 반면, ECR은 저장 용량 기준으로만 요금이 부과되고, AWS 내부 통신에는 별도의 비용이 들지 않아 비용 구조가 단순하고 예측 가능합니다.

따라서, 기업 환경에서 AWS의 EC2 및 RDS를 사용하고 있으며, 동일 리전 내에서의 이미지 Pull이 주로 발생하는 경우, AWS ECR이 비용 효율적이고 AWS 서비스와의 통합 측면에서도 유리합니다. 특히, 초기 개발 환경 설정 시 빈번한 이미지 Pull이 예상된다면, Pull 제한이 없는 AWS ECR이 적합하다고 생각하였습니다.

도커(Docker) 배우기 (3) - 볼륨 (Volume)

smink — Fri, 11 Apr 2025 11:05:15 +0900

Docker Volume(도커 볼륨)

도커 볼륨

✅ 컨테이너가 가진 문제점

Docker를 활용하면 특정 프로그램을 컨테이너로 띄울 수 있다. 이 프로그램에 기능이 추가되면 새로운 이미지를 만들어서 컨테이너를 실행시켜야 한다. 이 때, Docker는 기존 컨테이너에서 변경된 부분을 수정하지 않고, 새로운 컨테이너를 만들어서 통째로 갈아끼우는 방식으로 교체를 한다. 이게 효율적이라고 생각했던 것이다.

이런 특징 때문에 기존 컨테이너를 새로운 컨테이너로 교체하면, 기존 컨테이너 내부에 있던 데이터도 같이 삭제된다. 만약 이 컨테이너가 MySQL을 실행시키는 컨테이너였다면 MySQL에 저장된 데이터도 같이 삭제 돼버린다.

따라서 컨테이너 내부에 저장된 데이터가 삭제되면 안 되는 경우에는 볼륨(Volume)이라는 개념을 활용해야 한다.

(ex. MySQL과 같은 DB는 해당 컨테이너 환경에 데이터가 저장이 되는데, 그런데 이 컨테이너를 통째로 교체한다고 하면 해당 컨테이너에 저장되어있던 데이터가 같이 삭제되어버리는 문제가 발생한다.)

✅ Docker Volume(도커 볼륨)이란?

도커의 볼륨(Volume)이란 도커 컨테이너에서 데이터를 영속적으로 저장하기 위한 방법이다. 볼륨(Volume)은 컨테이너 자체의 저장 공간을 사용하지 않고, 호스트 자체의 저장 공간을 공유해서 사용하는 형태이다.

-> 컨테이너 지울 때 데이터 같이 안 날라가게 하는 방법!

도커 볼륨

✅ 볼륨(Volume)을 사용하는 명령어

$ docker run -v [호스트의 디렉토리 절대경로]:[컨테이너의 디렉토리 절대경로] [이미지명]:[태그명]

[호스트의 디렉토리 절대 경로]에 디렉토리가 이미 존재할 경우, 호스트의 디렉터리가 컨테이너의 디렉터리를 덮어씌운다.

절대경로에 디렉토리가 존재할 경우

[호스트의 디렉토리 절대 경로]에 디렉토리가 존재하지 않을 경우, 호스트의 디렉터리 절대 경로에 디렉터리를 새로 만들고 컨테이너의 디렉터리에 있는 파일들을 호스트의 디렉터리로 복사해온다.

절대경로에 디렉토리가 존재하지 않을 경우

도커(Docker) 배우기 (2) - 자주 쓰는 명령어(Docker CLI)

smink — Fri, 4 Apr 2025 14:10:03 +0900

도커(Docker) 배우기 (2) - 자주 쓰는 명령어(Docker CLI)

도커 이미지(Docker Image) 관련 명령어

이미지(Image)를 다운 받는 명령어

docker pull {ImageName} docker pull {ImageName}:{TagName}

이미지 목록 조회 (Image List)
```
docker image ls
```
이미지 삭제 (Image Remove)
```
docker image rm {ImageID} docker image rm {ImageName}
```
- Id가 너무 길고 복잡하기 때문에 일부분만 타이핑해도 삭제가 된다!
- 실행중인 컨테이너의 이미지는 삭제하지 못한다.
중단시킨 컨테이너에서 이미지를 사용중이라면
```
docker image rm -f {ImageID}
```
컨테이너에서 사용하지 않는 전체 이미지 삭제
```
docker image rm $(docker images -q) docker image rm -f $(docker images -q)
```
도커 컨테이너(Docker Container) 관련 명령어
(실행중인) 컨테이너 조회

docker ps

-   \-a : 중단된 컨테이너도 조회

컨테이너 생성

docker create {ImageName}

-   Image가 없으면 알아서 찾아보고 다운로드까지 해줌

컨테이너 실행

docker start {Container ID}

컨테이너 중단

docker stop {Container ID}
docker kill {Container ID}

-   stop : 시스템 종료 버튼을 통해 정상적으로 종료하는 방법
-   kill : 컴퓨터 전원버튼 꾹 눌러 끄듯이 강제로 끄는 방법

컨테이너 삭제

docker rm {Container ID}
docker rm -f {Container ID}

컨테이너 생성 & 실행

docker run {ImageName}
docker run --name {ContainerName} -d -p {HostPort}:{ContainerPort} {ImageName}\[:TagName\]

컨테이너 로그 조회

특정 컨테이너의 모든 로그 조회

# docker logs [컨테이너 ID 또는 컨테이너명]
$ docker run -d nginx
$ docker logs [nginx가 실행되고 있는 컨테이너 ID]

최근 로그 10줄만 조회

# dokcer logs --tail [로그 끝부터 표시할 줄 수] [컨테이너 ID 또는 컨테이너명]
$ dokcer logs --tail 10 [컨테이너 ID 또는 컨테이너명]

기존 로그 조회 + 생성되는 로그를 실시간으로 보고 싶은 경우

# docker logs -f [컨테이너 ID 또는 컨테이너명]
# Nginx의 컨테이너에 실시간으로 쌓이는 로그 확인하기
$ docker run -d -p 80:80 nginx
$ docker logs -f

-f : follow의 약어

기존 로그는 조회하지 않기 + 생성되는 로그를 실시간으로 보고 싶은 경우
```
$ docker logs --tail 0 -f [컨테이너 ID 또는 컨테이너명]
```

실행 중인 컨테이너 내부에 접속하기

# docker exec -it 컨테이너명[또는 컨테이너 ID] bash

$ docker run -d nginx 
$ docker exec -it [Nginx가 실행되고 있는 컨테이너 ID] bash 
$ ls # 컨테이너 내부 파일 조회 
$ cd /etc/nginx 
$ cat nginx.conf

컨테이너 내부에서 나오려면 Ctrl + D 또는 exit을 입력하면 된다.
bash : 쉘(Shell)의 일종
-it : -it옵션을 사용해야 명령어를 입력하고 결과를 확인할 수 있다. -it옵션을 적지 않으면 명령어를 1번만 실행시키고 종료되어 버린다. 즉, -it 옵션을 적어야 계속해서 명령어를 입력할 수 있다.
도커 이미지를 어디서 다운받았나?
Docker hub 에서 {이미지 명} 검색 -> 들어가보면 거기에 있는 이미지를 다운받은 것!
Image에서 Tags 를 누르면 각 Image의 version을 볼 수 있다.
Docker hub : GitHub 처럼 도커 이미지를 저장, 다운로드 할 수 있는 곳.

도커(Docker) 배우기 (1) - 컨테이너(Container), 이미지(Image) 란?

smink — Thu, 3 Apr 2025 17:19:19 +0900

Docker

컨테이너(Container)를 사용하여 각각의 프로그램을 분리된 환경에서 실행 및 관리할 수 있는 툴

✅ 컨테이너 (Container)

하나의 컴퓨터 환경 내에서 미니 컴퓨터 환경을 여러개 만들어서 분리해서 사용할 수 있도록 해둔 형태

ex) 윈도우에 사용자1, 사용자2가 있을 때 사용자1이 카톡을 깔았다고해서 사용자2한테 카톡이 안깔리는것 처럼 독립적인 환경

☑️ 컨테이너(Container)의 독립성

디스크 (저장 공간) : 각 컨테이너 마다 각자의 저장 공간 보유. 일반적으로 A 컨테이너 에서 B 컨테이너 내부 파일 접근 불가
네트워크 (IP, Port) : 각 컨테이너 마다 고유의 네트워크를 가지고 있다. 컨테이너는 각자의 IP 주소를 가지고있다.

✅ 이미지 (Image)

이미지(Image)는 프로그램을 실행하는 데 필요한 설치 과정, 설정, 버전 정보 등을 포함하고 있다.

-> 프로그램을 실행하는 데 필요한 모든 것을 포함하고 있다.

ex1) 닌텐도 게임 칩 처럼 하나의 게임기에 여러개 칩을 꽂아서 다양한 게임을 즐기는 것과 유사함

ex2) SpringBoot 프로젝트를 이미지로 만든다면, 이 이미지를 Docker로 실행시키면 SpringBoot Server가 컨테이너(Container) 환경에서 복잡한 설치 과정을 거칠 필요 없이 손쉽게 실행 된다. (= SpringBoot Server가 미니 컴퓨터 환경에서 실행된다.)

Github Actions EC2 CI/CD 서버 멈춤 현상

smink — Wed, 2 Apr 2025 20:24:50 +0900

GitHub Actions으로 SpringBoot API Server의 CI/CD를 구현해놓았다.
그런데 Merge를 하고나서 얼마안가 서버가 계속 멈추는 현상이 발생했다.
사유는 다음과 같았다.

1. 발생 원인

1. EC2 RAM 사용량

EC2에서 평소 사용중인 메모리가 4기가 중에서 1.8~2.1기가 정도이다.
Github Action을 통해 서버 내에서 SpringBoot 프로젝트를 빌드하는 과정에서 메모리 사용량이 늘어나면서 3기가 이상으로 늘어나면서 생긴 문제였다.

2. CI/CD 과정

사실 아직 초보 개발자라 이게 올바른 CI/CD 방법인가에 대한 고민은 한가득이다.

어떠한 방법이 맞는지에 대한 정답?은 없다고들 하지만 최선은 있지않은가... 고수님들 알려주세요...ㅠㅠ
현재 배포하는 과정은 다음과 같다.

Main branch Merge ->

Github Actions

name: Deploy Spring Boot App

on:
  push:
    branches: [ "main" ]

env:
  SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
  SERVER_USER: ${{ secrets.SERVER_USER }}
  SERVER_HOST: ${{ secrets.SERVER_HOST }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Execute deploy script on server
        run: |
          echo "${SSH_PRIVATE_KEY}" > private_key
          chmod 400 private_key
          ssh -i private_key -o StrictHostKeyChecking=no ${SERVER_USER}@${SERVER_HOST} 'bash /home/ubuntu/appServerDeploy.sh'
      - name: Clean up
        run: rm -f private_key

Github Actions에 의한 deploy.sh 실행

#!/bin/bash


# 소스 코드 최신화

cd ~/{projectRoot}/

echo "git pull origin main"

git pull origin main

echo "springBoot Build && nohup Deploy"




# Spring Boot 프로젝트 빌드

cd ~/{projectRoot}

./gradlew build



# 기존 실행 중인 Spring Boot 애플리케이션 종료

SPRING_PORT=8080
SPRING_PID=$(lsof -t -i:$SPRING_PORT)
if [ -n "$SPRING_PID" ]; then
  echo "SPRING_PID : $SPRING_PID"
  echo "Stopping existing Spring Boot application on port $SPRING_PORT (PID: $SPRING_PID)"
  kill -9 $SPRING_PID
else
  echo "No application running on port $SPRING_PORT"
fi

# Spring Boot 프로젝트 실행
nohup java -jar ~/{projectRoot}/build/libs/app-0.0.1-SNAPSHOT.jar &



# 실행 중인 Spring Boot 애플리케이션 확인

echo "Verifying Spring Boot application..."
sleep 5
ps -ef | grep app-0.0.1-SNAPSHOT.jar

이렇게 서버에서 빌드를 하고 배포를 하다보니 빌드 과정에서 서버의 메모리를 일시적으로 많이 쓴다는걸 확인했다.

2. 해결 방법

1. 프로젝트 빌드 시점

첫번째로 생각한 해결 방법은 프로젝트 빌드를 AWS EC2 서버에서 하는것이 아니라, Github Action 내부에서 빌드 후 서버로 .jar를 옮겨주는 방법이다.

✅ .jar 파일을 GitHub Actions에서 빌드 후 서버로 옮겨주면 좋은 점

EC2 서버의 메모리 부담 감소: 현재는 EC2에서 빌드 과정에서 메모리를 많이 사용하여 서버가 멈추는 문제가 발생했다. GitHub Actions에서 빌드하면 EC2의 메모리 사용량이 줄어든다.
배포 속도 향상: EC2에서 빌드를 진행하면 CPU와 메모리를 사용하면서 시간이 오래 걸릴 수 있다. GitHub Actions의 빌드 서버는 고성능 환경이므로 더 빠르게 빌드할 수 있다.
일관된 빌드 환경 유지: 로컬 개발 환경, EC2 환경이 달라 발생할 수 있는 빌드 이슈를 방지할 수 있다.

❌ 하지만 이렇게 하지 않고 기존 방식(EC2에서 빌드) 유지한 이유

GitHub Actions에서 빌드하려면 빌드 결과물을 EC2로 전송하는 과정이 추가된다. (scp 명령어)
EC2에서 바로 빌드하면 소스 코드와 빌드 결과물이 같은 환경에 존재하므로 관리가 편하다.

2. 스왑 메모리 설정

EC2 설정을 보니 스왑메모리가 설정되어있지 않았다.

스왑 메모리를 사용하여 RAM이 부족하더라도 서버가 멈추지 않게 할 수 있다.

✅ 스왑 메모리를 설정하면 좋은 점

메모리 부족 문제 완화: RAM이 부족할 때 스왑 메모리를 사용하면 프로세스가 종료되지 않고 지속적으로 실행될 수 있다.
서버 안정성 증가: 빌드 과정에서 순간적으로 메모리 사용량이 급증하는 경우에도 서버가 멈추지 않는다.
비용 절감: EC2의 인스턴스 타입을 업그레이드하는 것보다 스왑 설정이 비용 측면에서 효율적일 수 있다.

❌ 하지만 스왑 메모리를 설정할 때 고려할 점

스왑은 디스크(I/O)를 사용하기 때문에 성능이 저하될 가능성이 있다.
스왑을 너무 크게 설정하면 불필요한 디스크 I/O가 증가하여 오히려 성능이 떨어질 수 있다.

3. 내가 선택한 해결 방법

스왑 메모리 설정

- 스왑 메모리를 설정한 이유

우선적으로는 기존 배포 프로세스를 변경하지 않고 간단한 설정 변경만으로 해결 가능했기 때문이다.

또한 빌드뿐만 아니라 다른 작업에서도 언젠가는 발생할 수 있는 문제였기에 어느 시점에서는 꼭 필요한 작업이었다.

스왑 메모리 설정 방법

스왑 파일 생성
먼저, 2GB 크기의 스왑 파일을 생성한다.
sudo fallocate -l 2G /swapfile
만약 fallocate가 지원되지 않는 경우, dd 명령어를 사용할 수도 있다.
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048
스왑 파일 권한 변경
보안 강화를 위해 스왑 파일의 권한을 600으로 설정한다.
sudo chmod 600 /swapfile
스왑 영역으로 설정
생성한 파일을 스왑 영역으로 지정한다.
sudo mkswap /swapfile
스왑 활성화
sudo swapon /swapfile
스왑 적용 확인
스왑이 정상적으로 설정되었는지 확인한다.
free -h 또는 swapon --show
재부팅 후에도 유지되도록 설정
EC2는 인스턴스를 재부팅하면 스왑 설정이 사라지므로, /etc/fstab에 설정을 추가해야 한다.
echo '/swapfile swap swap defaults 0 0' | sudo tee -a /etc/fstab

- 왜 deploy.sh와 GitHub Actions의 workflow를 변경하지 않았는가?

EC2에서 빌드하는 방식도 충분히 가능하며, 단순히 메모리 문제를 해결하는 것이므로 굳이 구조를 변경할 필요가 없었다.

또한 지금은 개발 초기단계에서 적용하는 부분에서 편리하기 위해 구현된 간단한 CI/CD이기 때문이다.

향후 Docker와 Kubernetes를 도입해 자동 복구(Self Recovery)를 구현할 계획이었기에 배포 스크립트와 github actions에 큰 힘을 쏟지 않아도 된다고 생각했다.