개발하는 자몽

[AWS] CloudWatch 사용해보기 2: 커스텀 지표 수집 및 커스텀 대시보드 생성

jaamong — Sat, 6 Dec 2025 10:03:52 +0900

지난 글에서는 AWS가 기본적으로 여러 네임스페이스와 지표를 제공하는 것을 확인했었다. 기본 제공 데이터 외에도 사용자가 커스텀 지표를 생성하여 이 지표가 속하는 네임스페이스를 생성할 수도 있다.

커스텀 지표 수집

커스텀 지표를 생성하는 이유는 AWS에서 기본 제공하는 지표로는 확인할 수 없는 항목들이 있기 때문이다. EC2 메모리 및 디스크와 관련된 지표들은 AWS에서 기본 제공하지 않고, EC2 인스턴스에 CloudWatch agent를 설치하여 커스텀 지표를 수집하도록 설정해야 한다.

진행하는 환경은 EC2 - Ubuntu 24.04 LTS이다.

기본 제공하지 않고 OS에 설치해야 하는 이유

Agent 설치

IAM 역할 생성

EC2에게 부여할 IAM 역할부터 생성하자. 이 역할은 EC2가 지표를 수집하고, 로그를 포함하여 CloudWatch로 보낼 수 있는 권한을 갖는다.

"IAM > 역할"로 이동하여 역할 생성을 선택한다.
1단계 - 신뢰할 수 있는 엔터티
- 신뢰할 수 있는 엔터티 유형: AWS 서비스
- 사용 사례: EC2
2단계 - 권한 추가
- 검색창에 `CloudWatchAgentServerPolicy`를 입력 및 선택한다. 다음으로 넘어간다.
3단계 - 이름 지정, 검토 및 생성
- 역할 이름과 설명은 자유롭게 입력하되, 어떤 목적으로 생성되었는지 드러나도록 작성한다. 이제 완료.

이제 생성한 역할을 EC2에 부여해야 한다.

"EC2 > 인스턴스"로 이동하고 역할을 부여해야 하는 EC2를 선택하자. 선택하고 "작업 > 보안 > IAM 역할 수정"을 수행한다. 이동한 화면에서 방금 생성한 역할을 선택하고 완료한다.

에이전트 설치 (Ubuntu 기준)

EC2에 접속한 상태에서 진행한다.

에이전트 패키지를 다운로드한다.

wget https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb

다운로드한 패키지를 설치한다.

sudo dpkg -i -E ./amazon-cloudwatch-agent.deb

설치 파일 위치로 이동한다.
```
cd /opt/aws/amazon-cloudwatch-agent/bin
```
에이전트를 실행한다.
```
./amazon-cloudwatch-agent-config-wizard
```

실행하면 다음의 질문들이 나온다. (작성할 때 라이브로 진행한 게 아니라서 조금 다를 수 있지만, 큰 틀은 벗어나지 않는다)

1. On which OS are you planning to use the agent?
 => linux 
2. Are you using EC2 or On-premises hosts?
 => EC2
3. Which user are you planning to run the agent?
 => root
4. Do you want to turn on StatsD daemon?
 => no
5. Do you want to monitor metrics from CollectD?
 => no
6. Do you want to monitor any host metrics? e.g. CPU, memory, etc.
 => yes
7. Do you want to monitor cpu metrics per core?
 => no
8. Do you want to add ec2 dimensions (ImageId, InstanceId, InstanceType, AutoScalingGroupName) into all of your metrics if the info is available?
 => yes
9. Do you want to aggregate ec2 dimensions (InstanceId)?
 => yes
10. Would you like to collect your metrics at high resolution (sub-minute resolution)? This enables sub-minute resolution for all metrics, but you can customize for specific metrics in the output json file.
 => 60s 
11. Which default metrics config do you want?
 => Basic (각 옵션마다 수집할 수 있는 지표가 다르며, Basic은 가장 적다.)

---json 파일로 된 configration---

12. Are you satisfied with the above config? Note: it can be manually customized after the wizard completes to add additional items.
 => yes
13. Do you have any existing CloudWatch Log Agent(<http://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AgentReference.html?) configuration file to import for migration?
 => no
14. Do you want to monitor any log files?
 => no 
15. Do you want to specify any additional log files to monitor?
 => no
16. Do you want to store the config in the SSM parameter store?
 => no

"Program exits now"라는 문장이 출력되면 설정이 완료됐다.

설정(config)을 변경하고 싶다면 /opt/aws/amazon-cloudwatch-agent/bin/config.json 파일을 수정하자.

이후 에이전트를 실행하자. (설정 파일을 수정한 뒤에도 이 명령을 실행하면 된다.)

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:/opt/aws/amazon-cloudwatch-agent/bin/config.json -s

설정이 잘 되었다면 5분 뒤에 "CloudWatch > Metrics"에서 사용자 지정 네임스페이스 하위에 있는 `CWAgent` 네임스페이스를 확인할 수 있다. 이 네임스페이스에서 메모리 및 디스크와 관련된 지표를 확인할 수 있다.

CWAgent 네임스페이스 > InstanceId (dimension > disk, mem 지표

추가

에이전트 상태 확인 명령어

/opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent.log

에이전트 에러 관련 로그 위치

amazon-cloudwatch-agent-ctl -m ec2 -a status

커스텀 대시보드 생성

CWAgent 네임스페이스에서 메모리 및 디스크 관련 지표를 확인했다면 이번에는 해당 지표들을 하나의 위젯으로 묶어 대시보드에서 확인할 수 있도록 하자. 만들고자 하는 대시보드에는 두 개의 위젯을 담을 것이다.

EC2 상태를 알 수 있는 위젯
메모리, 디스크 및 CPU 사용률 현황을 알 수 있는 위젯

EC2 상태 확인을 위한 지표를 간단히 알아보자. 기본 제공되는 지표는 세 가지로 볼 수 있다.

StatusCheckFailed_Instance
- 잘못 구성된 네트워킹 또는 시작구성
- 소진된 메모리
- 손상된 파일 시스템
- 호환되지 않는 커널
StatusCheckFailed_System
- 네트워크 연결 문제
- 시스템 전원 문제
- 물리 호스트의 소프트웨어 문제
- 물리 호스트의 하드웨어 문제
StatusCheckFailed
- 위 2개 CheckFailed의 OR 조건

위 지표들은 AWS/EC2 네임스페이스의 인스턴스별 지표 차원에서 확인할 수 있다. 해당 지표들을 선택하고 "작업 > 대시보드에 추가"를 클릭한다.

나타나는 화면에서 요구하는 정보들을 입력한다.

대시보드 선택: 별도로 생성해 둔 대시보드가 없다면 새로 생성을 선택
- 새로 생성을 선택하면 '새 대시보드 생성'란이 나타난다. 생성할 대시보드 이름을 입력하고 생성을 클릭한다.
위젯 유형: 자유롭게 선택
위젯 제목 사용자 지정: 선택한 지표들은 하나의 위젯으로 대시보드에 속하게 된다. 이 위젯을 뭐라고 칭할지 정하면 된다. 지금 선택한 지표들은 EC2의 상태를 나타내므로 간단히 `EC2 status`라고 명명했다.

대시보드에 추가를 선택하여 완료한다.

이제 "대시보드 > 사용자 지정 대시보드"로 이동하면 방금 생성한 대시보드 이름을 확인할 수 있다. 이름을 클릭하면 지표들을 묶은 위젯도 확인할 수 있다. 위젯은 생성 이후에도 편집할 수 있으므로 상황에 따라 지표 추가 및 제거를 편리하게 할 수 있다.

두 번째 위젯도 만들어 보자. 우선 `CWAgent` 네임스페이스에서 `mem_used_percent`, `disk_used_percent` 지표를 선택하여 생성한 대시보드에 추가하자. 그다음 생성한 위젯에서 편집을 클릭하여 `CPUUtilization` 지표를 선택하면 두 번째 위젯도 완성이다.

요금

사용자 지정 네임스페이스 - 지표

사용자 지정 네임스페이스에 속한 지표는 개당 월별 0.30 USD가 청구된다. (전체 지표수가 1만 개를 초과하는 경우 볼륨 요금 티어가 적용된다.) Resolution을 '60초'로 설정하고, 지표 설정을 'Basic'으로 설정했을 때 생성되는 `CWAgent` 네임스페이스에서 23개의 지표를 수집할 수 있다. 따라서 23개의 지표에 대한 월별 비용은 23 metrics × 0.30 USD = 6.90 USD가 된다.

커스텀 대시보드

또한 AWS에 의해 자동으로 생성되는 대시보드 외에 커스텀 대시보드를 사용하는 경우, 대시보드당 3.00 USD가 청구된다. 지금처럼 한 개의 커스텀 대시보드가 있는 경우에는 월별 비용이 1 dashboard × 3.00 USD = 3.00 USD가 된다.

경보(Alarm)

이 글에서 다루지는 않았지만 특정 지표에 대한 CloudWatch 알람을 설정하면, 알람이 트리거 되지 않아도 생성 즉시 비용이 청구된다. 해당 비용은 알람 당 월별 0.10 USD이며, 실제로 알람이 트리거 되어 SNS 알림이 발생하면 별도 비용이 청구된다.

끝!

CloudWatch에 관하여 간단하게 알아보았다. 더 많은, 복잡한 기능들이 있지만, 우선 이 정도만 알아둬도 나머지는 좀 더 수월하게 알아갈 수 있다고 생각한다.

참고로 요금에서 언급한 경보는 설정하는 방법이 복잡하거나 어렵지 않으므로 시도해 보면 좋을 것 같다. `CPUUtilization`이 70%를 초과하면 알림이 오도록 설정해 보는 건 어떨까. 알기로는 이메일뿐만 아니라 Slack으로도 알림을 받을 수 있다. 처음에는 이메일로 설정해 보고 Slack으로도 받아보도록 해보자. (이 부분은 추가 요금이 발생할 수도 있다.)

마지막으로, 언제나 요금 폭탄을 조심하자. 안 쓰는 대시보드나 알람은 바로바로 삭제하기!

[AWS] CloudWatch 사용해보기 1: 용어 소개

jaamong — Fri, 5 Dec 2025 22:00:36 +0900

목적

Amazon CloudWatch는 AWS, 온프레미스 및 기타 클라우드에서 리소스 및 애플리케이션을 관측하고 모니터링할 수 있는 서비스이다. 이를 이용하여 성능 변화에 대응하고 리소스 사용을 최적화하고, 운영 상태에 대한 인사이트를 얻을 수 있다.

CloudWatch는 로그(수집, 보관 등) 및 수집하는 커스텀 지표 등이 적을 때는 비용이 크게 청구되지 않지만, 잘 모르고 사용하면 예상하지 못한 금액을 보게 되는 서비스라고 생각한다. 비용에 관한 자세한 내용은 공식 문서를 참고하자.

나도 많이 아는 건 아니지만, 알아두면 좋은 내용들을 기록 및 공유를 위해 작성하려고 한다.

다음 내용을 다룰 예정이며, 이 포스팅에서는 우선 용어 소개만 다루려고 한다.

알아두면 좋은 CloudWatch 용어 소개
사용자 커스텀 지표 및 수집 방법
Amazon CloudWatch agent 설치 방법
사용자 커스텀 대시보드 생성 방법

지표 관련 용어

CloudWatch의 모든 지표 메뉴로 가면 사용하고 있는 리소스에 관한 다양한 정보를 얻을 수 있다. 이에 관하여 CloudWatch에서 사용하는 단위는 네임스페이스(Namespace), 지표(Metric), 차원(Dimension) 등이 있다.

네임스페이스(Namespace)

네임스페이스는 특정 서비스 또는 리소스 그룹에 대한 지표들을 묶어서 분류하는 단위로 EC2, S3, ELB 등이 해당된다. 각 리소스는 서로 다른 네임스페이스에 속하며, 각 네임 스페이스는 리소스의 상태를 나타내는 다양한 지표를 제공한다.

AWS에서 기본적으로 제공되는 네임스페이스는 ` AWS/service`로 명명된다. 예를 들어, EC2 네임스페이스는 `AWS/EC2`라는 이름을 갖는다.

AWS에서 기본적으로 제공하는 네임스페이스 일부

지표(Metric)

지표는 AWS 서비스가 보내는(publish) 시계열 데이터 포인트 집합으로 구성된다. 데이터 포인트(data points)는 특정 시점에서의 단일 지표 값 또는 관측값으로, 단순하게 말하자면 시간 순으로 정렬된 '시간-값'으로 표현되는 데이터라는 뜻이다. 아래 사진에서 볼 수 있듯이 AWS/EC2 네임스페이스에서 CPU 사용률을 나타내는 `CPUUtilization` 지표를 선택하면 시간별 CPU 사용률(값)을 확인할 수 있다.

데이터 포인트에는 Resolution와 Period이라는 개념이 있다. Resolution은 데이터가 얼마나 자주 수집되는지 의미한다. 주요 서비스에 대한 지표는 기본적으로 5분 또는 1분/60초 마다 수집되며(Standard resolution) 무료로 제공된다. 1초 단위 이상으로 수집할 수 있는 High resolution 모드는 별도로 요금이 부과된다. (참고로 Resolution은 해상도로 번역하는 것이 의미상 가깝다고 한다.)

Period는 데이터 포인트가 얼마만큼의 시간을 기준으로 묶여서 보내지는지를 의미한다. 예를 들어, "매 60초 간격으로 묶어 보겠다." 하면 '매 60초'가 period가 된다.

참고로 period가 짧을 수록 보관 기간(retention period)도 짧아진다. 작은 단위의 보관 기간은 큰 단위로 합쳐지므로, 데이터가 사라지는 것은 아니다.
관련 자료

AWS/EC2 네임스페이스의 지표들

우리가 위 사진을 통해 "EC2의 CPU 사용률을 확인한다"라고 했을 때 EC2가 네임스페이스가 되고, CPU 사용률은 지표가 된다.

차원(Dimension)

차원은 지표를 더 세부적으로 분류할 수 있도록 하는 이름/값 쌍이다. 따라서 차원으로 각 지표를 식별할 수 있다. 아래 사진에서 `InstanceId`가 차원이다. 아래의 화면에서 특정 `InstanceId`에 마우스 커서를 대면 검색에 추가/제외할 수 있는 버튼이 생긴다(필터링). 이런 식으로 차원을 통해 지표를 식별할 수 있게 된다.

AWS/EC2 차원 - InstanceId

아래처럼 형광색으로 표시된 항목들도 차원이다. `AWS/ApplicationELB` 네임스페이스 하위에 있는 지표들을 특정 기준에 따라 분류해 둔 것이다.

AWS/ApplicationELB 차원

용어 소개는 여기까지이다. 자세히 다루지는 않았지만, 이 정도만 알아도 CloudWatch를 처음 다룰 때 당황스럽지는 않다.

다음 글에서는 CloudWatch agent 설치와 커스텀 지표 수집 및 커스텀 대시보드 생성을 다룬다.

[CI/CD] AWS + Docker + GitHub Actions Self-hosted runner

jaamong — Fri, 28 Nov 2025 10:34:52 +0900

목표

GitHub Actions Self-hosted runner 기능을 사용하여 AWS EC2 인스턴스에 배포되고 있는 FastAPI 애플리케이션에 대해 CI/CD를 적용하자. 또한 환경 변수(.env) 적용 및 간단하고 편리한 빌드를 위해 Docker를 함께 사용할 것이다.

보통 GitHub Actions를 사용하여 구축하는 CI/CD의 빌드는 깃허브에서 진행하게 된다(GitHub-hosted runner). Self-hosted runner는 깃허브가 아닌 사용자가 지정하는 컴퓨팅 자원에서 빌드를 진행하도록 하는 시스템이다. 이 글에서는 EC2에서 빌드를 진행하도록 할 것이다.

이 과정에서는 다음의 기능들을 사용하여 CI/CD를 구축한다.

GitHub Actions Self-hosted runner
Docker
- Dockerfile
- docker-compose.yml: 환경 변수 적용 및 로깅 드라이버 설정을 위함
AWS
- ECR : Docker 이미지 저장 및 관리
- IAM OIDC, Role
  - OIDC: GitHub Actions에서 AWS ECR로 이미지 업로드를 할 때 필요함
  - Role: EC2가 ECR에 접근하여 이미지를 가져오기 위해 필요함
- EC2
  - AMI는 Ubuntu 24.04 LTS으로 진행한다.
- EIP
  - 도메인없이 외부에서 EC2(애플리케이션)로 접근하기 위해 IP 할당

Notice

지금은 EC2 인스턴스가 퍼블릭 서브넷에 위치하므로 EIP를 사용하지만, 보안을 고려한다면 프라이빗 서브넷에 두어야 한다. 그리고 인터넷 통신을 위해 앞에 NAT Gateway나 ELB 같은 서비스를 사용해야 한다.

일단 이 글의 목적은 GitHub Actions Self-hosted runner & Docker & AWS를 사용하여 CI/CD를 구축하는 것이기 때문에 이 부분은 넘어간다.

과정

다른 CI/CD 방법보다 진행하는 과정이 어렵거나 복잡하지 않기 때문에 간단하게 작성한다.

AWS 리소스부터 생성한다.

1. 보안 그룹 생성

"EC2 > 네트워크 및 보안 > 보안 그룹"으로 이동 후 보안 그룹 생성 클릭
- 기본 세부 정보
  - 보안 그룹 이름: 보통 프로젝트 명 + 'sg' 접미사를 합쳐서 작성 (예: todolist_be_sg, todolist_app_sg,...)
  - 설명: 무엇을 위한 보안 그룹인지 간단히 작성
  - VPC: 애플리케이션을 배포하고 있는 EC2가 위치한 VPC 선택
- 인바운드 규칙 1
  - 유형: SSH
    - SSH를 통해 EC2 접속을 하기 위함
  - 소스 유형: Anywhere-IPv4
    - SSH에 한하여 모든 곳에서 요청받음
  - 설명: 이 규칙이 어떤 용도인지 간단히 작성
- 인바운드 규칙 2
  - 유형: HTTP (HTTPS 프로토콜은 이 글에서 다루지 않음)
  - 소스 유형: Anywhere-IPv4
    - HTTP에 한하여 모든 곳에서 요청받음
  - 설명: 이 규칙이 어떤 용도인지 간단히 작성
아웃바운드 규칙은 건들지 않고 완료. 보안 그룹 생성 클릭

2. EC2 인스턴스 생성

"EC2 > 인스턴스 > 인스턴스"로 이동 후 인스턴스 시작 클릭
1. 이름 및 태그: 보통 프로젝트 이름을 작성하고 여기에 파트(be, fe,...), 'app' 등을 덧붙임 (예: todolist-be-app)
2. 애플리케이션 및 OS 이미지(AMI): 이 글은 우분투(Ubuntu 24.04 LTS)로 진행한다.
3. 인스턴스 유형: 인스턴스 내부에 runner와 docker를 설치 및 실행해야 하므로 `micro`보다 큰 `small`부터 선택하는 것을 추천한다. 단순 연습용이라면 `t3.small`이 좋다. (micro는 도커 돌리다가 CI/CD 하기도 전에 서버가 다운될 수도.. 경험담이다)
4. 키 페어(로그인): 사용하던 키 페어를 사용해도 좋고, 별도로 없다면 새 키 페어 생성을 클릭한다.
  - 키 페어 이름: 어떤 키 페어인지 식별할 수 있도록 작성
  - 키 페어 유형: RSA
  - 프라이빗 키 파일 형식: .pem
5. 네트워크 설정
  - 방화벽(보안 그룹): 기존 보안 그룹 선택 → 1번에서 생성한 보안 그룹 선택
6. (Optional) 고급 세부 정보: 연습용이라면 스팟 인스턴스를 추천.
  - 구매 옵션: 스팟 인스턴스
    - 사용 중 예상치 못하게 자원이 반납될 수도 있지만, 대신 저렴하게 인스턴스를 대여할 수 있다. 연습 목적으로 적절하다.
7. 나머지는 기본 상태로 두고 완료. 인스턴스 시작 클릭.
잠시 기다리면 인스턴스 상태가 실행 중으로 나타남

3. EIP 할당 및 연결

"EC2 > 네트워크 및 보안 > 탄력적 IP"로 이동 후 탄력적 IP 주소 할당 클릭.
나타난 화면에서 틀린 내용이 없다면 할당 클릭.
생성 완료 후 할당한 EIP를 선택하고 "작업 > 탄력적 IP 주소 연결" 선택
- 인스턴스: 2번에서 생성한 인스턴스 선택
- 프라이빗 IP 주소: 자동으로 선택된 IP 주소가 정확한지 확인
- 나머지는 기본 상태로 두고 완료.
이제 EC2 인스턴스에 퍼블릭 IPv4 주소가 할당되었다.

참고로 24.02.01부터 사용 중인 EIP에도 시간당 IP당 0.005 USD가 부과되기 시작했다. 정확히는 퍼블릭 IPv4 주소에 대해 요금을 부과하는 것이다. 이는 IPv4 주소가 부족해지고 이로 인해 취득 비용이 증가하여, IPv6 선택을 장려하기 위함이라고 한다.
공식 문서 주소

4. AWS ECR 저장소 만들기

AWS ECR(Elastic Container Registry)은 Docker 컨테이너 이미지를 저장 및 관리할 수 있는 서비스로, S3를 저장소로 사용한다. 대용량으로 저장되지 않는 이상 보관 비용은 월별 USD 0.10/GB가 청구된다. 대용량이라고 방치하면 안 되고, 생각보다 금방 용량이 차기 때문에 항상 잘 관리해 주는 것이 좋다.

인터넷이나 동일 리전으로 수신하는 인바운드 데이터 전송에 대해서는 무료이며, 아웃바운드 데이터 전송에는 지역별로 GB 당 요금이 다르게 청구된다. 자세한 건 이 주소를 참고하자.

데이터 전송 요금이 나오는 이유는 ECR이나 S3가 VPC 밖에 위치하기 때문이다. EC2 인스턴스나 RDS 등의 리소스는 VPC>서브넷 내부에 위치하기 때문에 VPC 밖과 데이터를 주고받는 것에 대한 요금을 청구하는 것이다.

"ECR > 리포지토리 생성"으로 이동 후 리포지토리 생성 클릭.
리포지토리 이름: 다른 리소스를 생성할 때처럼 자유롭게 작성하되, 어떤 목적으로 생성하는지 잘 드러나게 한다.
이미지 태그 설정이미지 버전에 상관없이 태그가 덮어 씌워져도 상관없다면 `Mutable`, 버전 관리가 중요하다면 `Immutable`을 선택하면 된다. `Mutable`을 선택하더라도 "변경 가능한 태그 제외" 란에서 필터를 설정하여 변경할 수 없는 태그를 추가할 수 있다.
암호화 설정: 이 글에서는 `AES-256`을 선택한다.
생성 클릭.

5. IAM OIDC 공급자 추가 및 IAM 역할 생성

"IAM > 액세스 관리 > ID 제공 업체"로 이동 후, 공급자 추가 클릭
- 공급자 세부 정보
  - 공급자 유형: OpenID Connect
  - 공급자 이름: https://token.actions.githubusercontent.com
  - 대상: sts.amazonaws.com
- 공급자 추가 클릭하여 공급자 추가 완료
"IAM > 액세스 관리 > 역할"로 이동 후, 역할 생성 클릭
- 1단계 - 신뢰할 수 있는 엔터티 선택(신뢰 관계, trust policy 설정)

- - 신뢰할 수 있는 엔터티 유형: 웹 자격 증명
  - ID 제공업체: token.actions.githubusercontent.com
  - Audience: sts.amazonaws.com
  - GitHub organization: 배포할 레포지토리가 위치한 조직명
  - GitHub Repository: 배포할 레포지토리 이름
  - GitHub branch: 배포할 브랜치 이름
- 2단계 - 권한 추가
  - 아무것도 선택하지 않고 다음으로 이동
- 3단계 - 이름 지정, 검토 및 생성
  - 역할 이름: 해당 역할이 무엇을 하는지 드러나도록 작성. 보통 방향(AToB)을 드러내거나 어떤 서비스를 위한 것인지 (AForB) 작성하고 마지막에 'Role'을 붙이는 것 같다.
  - 설명: 빈칸 말고, 무엇을 위한 역할인지 '역할 이름'을 풀어서 작성하면 된다.
- 역할 생성 클릭

2번에서 생성한 역할을 클릭하고 "권한 > 권한 정책"으로 이동하여 권한 추가 > 인라인 정책 생성을 선택한다.

JSON을 선택하고 정책 편집기에 아래와 같이 작성한다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "GetAuthorizationToken",
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        },
        {
            "Sid": "ManageRepositoryContents",
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:GetRepositoryPolicy",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:DescribeImages",
                "ecr:BatchGetImage",
                "ecr:InitiateLayerUpload",
                "ecr:UploadLayerPart",
                "ecr:CompleteLayerUpload",
                "ecr:PutImage"
            ],
            "Resource": "arn:aws:ecr:ap-northeast-2:{aws-12-digit-account-id}:repository/{ecr-repo-name}"
        }
    ]
}

다음을 클릭하고, 나타나는 화면에서 정책이 어떤 일을 수행하는지 드러나도록 이름을 작성하고 완료한다.

방금 생성한 정책은 4번에서 만든 ECR 저장소에 Docker 컨테이너 이미지를 업로드하고, 가져오는 것을 허용하는 내용이 담겨있다. 예를 들어, 이 정책을 갖고 있는 역할을 EC2에 연결하면 EC2가 해당 권한(정책에 작성된 Action)을 갖게 된다. 이 과정에서는 GitHub Actions(OIDC 공급자)가 해당 권한들을 갖도록 설정했기 때문에 이 역할을 다른 리소스에 연결하지 않는다.

신뢰할 수 있는 엔터티

우리는 5-1에서 GitHub Actions가 맡은(assume role) IAM 역할의 '신뢰 관계(Trust Policy)'를 설정하여 이 OIDC 공급자를 신뢰할 수 있는 엔터티로 지정했다. 이를 통해 GitHub Actions 워크플로우 실행 시 GitHub Actions는 AWS Security Token Service(STS)로부터 임지 자격 증명을 발급받고, 이를 통해 AWS 내 필요한 리소스에 접근하여 작업을 수행할 수 있다.

6. Self-hosted runner 및 GitHub Secrets, Variables 설정

이제 runner를 설치해야 하므로 EC2 인스턴스에 접속할 준비를 하자.

Self-hosted runner 설치
1. "GitHub 레포지토리 > Settings > Actions > Runners"로 이동 후 New self-hosted runner 클릭
  - Runner image: Linux
  - Architecture: x64
2. `Download` 스크립트를 EC2 인스턴스에 접속하여 수행한다.
  - `label`은 Optional이지만, 프로젝트 또는 서비스 명 등으로 작성하면 실행해야 하는 runner를 식별하기 좋다.
3. `Download` 이후 `Configure`의 `./run.sh`은 지금 실행하지 않는다.
  - 해당 명령어로 runner를 실행하게 된다.
4. 이후 `actions-runner` 디렉토리 밖에서 다음 명령어를 차례대로 실행한다. 성공적으로 완료하면 runner가 실행되면서 build job을 감지하게 된다.
  1. `run.sh`를 `nohup`으로 실행하기 위한 스크립트를 생성하자. 여기서는 `vi`를 사용했는데 본인에게 맞는 편집기를 사용하면 된다.
```
$ vi run-bg.sh
```
  2. `vi` 창이 나타나면 `esc` → `i` 키를 순서대로 입력하고, 입력창이 활성화되면 아래 내용을 작성한다.
```
#!/bin/bash

nohup ./actions-runner/run.sh & > nohup.out  # nohup.out 파일이 생성되고, 여기에 run.sh 실행 로그 쌓임
```
  3. 작성 완료 후, `esc` → `:wq` → 엔터를 순서대로 입력한다.
  4. 터미널로 돌아오면 `./run-gb.sh` 명령어를 실행한다.
    - 이때 권한이 없어서 실행되지 않는다는 에러가 뜨면, 아래 명령어로 실행 권한을 추가하고 다시 시도한다.
```
$ chmod u+x run-bg.sh
```
  5. 실행 후 runner 상태를 확인하기 위해 다음으로 이동하자; "GitHub 레포지토리 > Actions > Runner > Self-hosted runners"
GitHub Secrets, Variables 설정
1. "GitHub 레포지토리 > Settings > Secrets and variables > Actions"로 이동한다.
2. Repository Secrets
  - AWS_ROLE_ARN: 5번에서 생성한 IAM Role의 ARN 값 (IAM 역할 정보에서 확인할 수 있다.)
3. Repository Variables
  - AWS_ACCOUNT_ID: 12자리 AWS 계정 ID
  - AWS_REGION: ap-northeast-2
  - ECR_REPOSITORY: 4번에서 생성한 ECR 레포지토리 이름

7. Dockerfile, docker-compose.yml 및 워크플로우 스크립트 작성

다음 파일들은 프로젝트 루트에 생성한다.
여기에서는 FastAPI 애플리케이션 버전으로 작성한다.
각 파일의 내용은 본인의 상황에 맞춰 수정해야 한다.

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# 의존성 파일 복사 및 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 애플리케이션 코드 복사
COPY . .

# uvicorn 실행
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml

지금 단계에서는 로깅 드라이버 설정을 포함하지 않는다.

services:
  fastapi-app:
    image: "${ECR_REGISTRY}/${ECR_REPOSITORY}:${IMAGE_TAG}"
    container_name: fastapi-app
    ports:
      - "80:8000"
    restart: unless-stopped
    env_file:
      - .env

.github/workflows/deploy.yml

다음 스크립트에서 `label`(runs-on)에는 `fastapi-app`가 추가되어 있다.

Notice 아래 내용은 사용하는 언어, 프레임워크, 도커 컨테이너 및 이름, 깃허브 변수 등에 따라 달라지므로 복붙하고 반드시 검토해야 한다.

name: Build and Deploy FastAPI to ECR

on:
  push:
    branches:
      - release
  workflow_dispatch:

permissions:
  id-token: write # Required for OIDC
  contents: read

jobs:
  build-and-push:
    runs-on: [self-hosted, fastapi-app]

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

      - name: Configure AWS credentials using OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ vars.AWS_REGION }}

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

      - name: Generate timestamp
        id: timestamp
        run: echo "timestamp=$(date +%Y%m%d-%H%M%S)" >> $GITHUB_OUTPUT

      - name: Build, tag, and push image to Amazon ECR
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: ${{ vars.ECR_REPOSITORY }}
          IMAGE_TAG: ${{ steps.timestamp.outputs.timestamp }}-${{ github.sha }}
        run: |
          docker build -t fastapi-app:$IMAGE_TAG .
          docker tag fastapi-app:$IMAGE_TAG $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          echo "Pushed image: $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"

      - name: Run new container using docker-compose
        env:
          # 여기에 .env 변수에 넣어야 하는 값(github secrets, variables)를 작성하면 된다. (예: DB 변수)
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: ${{ vars.ECR_REPOSITORY }}
          IMAGE_TAG: ${{ steps.timestamp.outputs.timestamp }}-${{ github.sha }}
          DB_HOST: ${{ secrets.DB_HOST }} # 예시
          
        run: |
          # ensure env file exists
          # 여기에서 .env 파일에 github secrets, variables 값들을 넣는다. 
          echo "ECR_REGISTRY=${ECR_REGISTRY}" >> .env
          echo "ECR_REPOSITORY=${ECR_REPOSITORY}" >> .env
          echo "IMAGE_TAG=${IMAGE_TAG}" >> .env
          echo "DB_HOST=${DB_HOST}" >> .env
  
          docker compose down
          docker compose pull
          docker compose up -d

      - name: Verify container is running
        run: |
          sleep 3
          if docker ps | grep -q fastapi-app; then
            echo "Container is running successfully"
            docker ps --filter name=fastapi-app
          else
            echo "Container failed to start"
            docker logs fastapi-app
            exit 1
          fi

      - name: Prune reclaimable Docker images and builder caches
        run: |
          sleep 10
          docker image prune -af 
          echo "Cleaned up reclaimable images..."
          docker builder prune -af
          echo "Cleaned up reclaimable builder caches..."

워크플로우의 마지막 단계는 사용하지 않는 이미지 및 빌드 캐시를 일괄 삭제한다. 진행하는 프로젝트의 도커 이미지 용량이 꽤나 커서 해당 단계를 넣었다.

8. GitHub 레포지토리에 Push

Commit & Push를 진행하고 워크플로우가 잘 동작하는지 확인하기 위해 다음으로 이동하자.

"GitHub Repository > Actions"로 이동
빌드가 성공적으로 완료되었다면 초록색 체크 표시를 확인할 수 있다.

+ Docker 로깅 드라이버 설정: AWS CloudWatch로 포워딩

EC2 인스턴스에서 실행되는 Docker 컨테이너의 로그는 보통 /var/lib/docker/containers 하위에 생성되고 쌓이게 된다. 로그는 생각보다 빠르게 용량을 잡아먹어서 관리하지 않으면 용량 부족으로 서버가 뻗어버릴 수 있다. 따라서 쌓인 로그를 주기적으로 관리해야 하며, 이 관리를 자동화하는 것을 추천한다.

방법에는 로그 로테이션 설정, 자동화 스크립트 w/cron, 로그 드라이버 변경 등이 있다. 여기에서는 로그 드라이버를 변경하여 AWS CloudWatch로 로그를 전송하도록 한다. 이 방법을 사용하면 EC2 인스턴스에 애플리케이션을 실행하는 Docker 컨테이너의 로그가 더 이상 쌓이지 않으므로, 로그로 인한 용량 문제는 걱정하지 않아도 된다.

이 방법은 이전에 소개한 적이 있으므로 이 글을 참고하면 된다.

참고로 로그를 CloudWatch로 전송할 때 GB 당 0.76 USD 비용이 청구된다. 이는 기본 로그 클래스(Standard log class)에서 커스텀 로그를 수집하는데 드는 비용이다. 또한 로그 데이터 양과 저장 기간에 대한 비용도 청구된다. GB 당 월별 0.0314 USD가 청구된다. 겉보기엔 크게 비용이 들진 않지만, 쌓이다 보면 비용이 급증하므로 로그 보존 기간을 적절히 설정하는 것이 좋다.

끝!

CI/CD 파이프라인 구축에 성공했다! 이제 EC2 인스턴스를 퍼블릭 서브넷에서 프라이빗 서브넷으로 옮기는 것을 시도하면 어떨까. 앞서 언급한 것처럼 프라이빗 서브넷으로 옮기면 외부와 소통하기 위한 추가적인 리소스가 필요하다. NAT Gateway나 ELB와 같은 서비스를 사용하면 되는데 이 둘은 생각보다 요금이 비싸다. 어떻게 하면 비용을 줄일 수 있을지 고민해 보는 것도 좋을 것 같다. (사람들은 어떻게든 길을 찾아낸다.)

이 CI/CD 파이프라인을 구성하는 리소스들의 비용은 다음처럼 예상할 수 있다.

GitHub Actions: 무료
AWS ECR: 월별 USD 0.10/GB (공식 문서 참고)
AWS EIP: 시간당 USD 0.005 → 3.65$/mo (USD 0.005 × 730 hr)
AWS EC2: t3.small을 선택했다면 0.025 USD/hr (온디맨드), 0.00925 USD/hr (스팟) → 18.25$/mo (USD 0.025 × 730 hr) , 6.7525$/mo (USD 0.00925 × 730 hr)
- EBS: 볼륨 요금도 잊지 말자. gp3 스토리지를 사용한다면 월별 GB당 USD 0.0912가 청구된다.
(Optional) AWS CloudWatch

물론 AWS는 다양한 방면으로 돈을 가져가기 때문에 더 청구될 가능성이 높다. 아니면 생각보다 덜 나갈 수도 있다! 비용이 너무 많이 청구되었다면 "결제 및 비용 관리"의 Cost Explorer와 청구서를 확인해 보자. 비용이 청구된 항목을 자세하게 분석할 수 있다.

그리고 보통 더 나가게 된다면 다음 항목일 가능성이 높으므로 확인해 보는 것을 추천하고 싶다.

VPC 관련 설정
데이터 이동/처리 비용
CloudWatch 로그 전송 및 보관 비용

CI/CD에 블루-그린 무중단 배포 적용하기: AWS ELB, AWS Auto Scaling Groups(ASG)

jaamong — Sat, 9 Aug 2025 21:44:18 +0900

꽤... 늦었는데, 지난번에 구축한 CI/CD에 블루-그린 무중단 배포를 적용해 보자.

지난 글: 2025.07.28 - [Architecture & Tool/AWS] - CI/CD 구축하기: GitHub Actions (OIDC) + Amazon S3 + Amazon CodeDeploy

보안 그룹

ALB 보안 그룹 생성

ALB를 생성하기 전에 보안 그룹을 만들자. EC2 > 보안 그룹으로 이동하여 보안 그룹 생성을 클릭한다.

아웃바운드 규칙은 건들지 않고 인바운드 규칙만 편집한다.

유형: HTTP
소스 유형: 사용자 지정
소스: 0.0.0.0/0

EC2 보안 그룹 수정

애플리케이션에 대한 요청을 ALB를 통해서만 받을 수 있도록 이전 포스트에서 생성했던 EC2 보안그룹을 수정해야 한다.

이전 포스트에서 두 개의 인바운드 규칙을 추가했었다.

외부에서 EC2 내부로 접속하기 위한 SSH 22번 포트에 관한 규칙
외부에서 EC2 내부에서 실행되고 있는 애플리케이션에게 요청을 보내기 위한 사용자 지정 TCP 8080(애플리케이션 별 다름)번 포트에 관한 규칙

이번에는 애플리케이션 실행 포트 번호에 대해서 수정해야 한다. 아래와 같이 수정하자.

유형: 사용자 지정 TCP
포트 범위: 8080 (애플리케이션이 실행되는 포트 번호)
소스 유형: 사용자 지정
소스: 앞서 생성한 ALB 보안 그룹을 선택 (ALB를 통해서만 요청을 받을 수 있게 됨)

SSH 관련 인바운드 규칙은 유지한다.

대상 그룹

보안 그룹은 말 그대로 보안을 위한, 리소스를 둘러싼 벽(방화벽, firewall)같은 거라 ALB가 받은 요청이 마법처럼 EC2에게 전달될 수 없다. 따라서 ALB와 EC2 인스턴스를 이어주는 다리가 필요하다. 이 다리 역할을 대상 그룹(Target Group)이 수행한다.

대상 그룹 생성

EC2 > 대상 그룹으로 이동하여 대상 그룹 생성을 클릭한다.

1단계: 그룹 세부 정보 지정

기본 구성: 인스턴스 ; ALB가 받은 트래픽을 인스턴스 단위로 전달(분산)할 것이므로
대상 그룹 이름: 자유롭게 입력(어떤 서비스를 위한 대상 그룹인지, 그리고 대상 그룹임을 명시하는 이름이 좋은 것 같다)
프로토콜: HTTP
포트: 8080 ; 앞서 수정한 EC2의 보안그룹의 포트와 동일해야 한다. 이 포트를 통해 ALB가 받은 트래픽이 라우팅 된다.
VPC: 트래픽을 받을 EC2 인스턴스가 존재하는 VPC를 선택한다.
상태 검사: 애플리케이션에 헬스 체크 API가 별도로 있다면, 상태 검사 경로에 해당 API의 엔드포인트를 입력한다.
언급하지 않은 나머지 항목들은 기본값을 유지하고, 다음으로 넘어간다.

2단계: 대상 등록

사용 가능한 인스턴스: 트래픽을 받을 인스턴스 선택 (앞서 보안그룹을 수정한 EC2를 선택하면 된다)
선택한 인스턴스를 위한 포트: 8080
아래에 보류 중인 것으로 포함 클릭
대상 그룹 생성 클릭

Application Load Balancer

EC2 인스턴스 앞에서 트래픽을 받아줄 로드밸런서를 생성할 차례다. EC2 > 로드 밸런서로 이동하고, 로드 밸런서 생성을 클릭한다. 로드 밸런서 유형은 Application Load Balancer를 선택한다.

로드 밸런서 이름: 자유롭게 입력
체계(schema): 인터넷 경계(internet-facing)
VPC: 대상 그룹과 EC2 인스턴스가 놓인 VPC와 동일해야 함
가용 영역 및 서브넷: 2개 이상 선택해야 한다. EC2 인스턴스와 다른 서브넷에 위치해도 상관없다.
- 이런 경우에서의 ALB 사용 사례를 잘 생각해보자. 보통 EC2 인스턴스를 프라이빗 서브넷에 놓는데(보안), 트래픽을 앞에서 먼저 받아 전달해 주는 ALB는 퍼블릭 서브넷에 놓는 편 → 둘은 다른 서브넷에 위치해도 OK.
보안 그룹: 처음에 ALB를 위해 생성했던 보안그룹을 선택
리스너 및 라우팅(다음 프로토콜 및 포트로 트래픽을 받아 대상 그룹으로 트래픽을 전달(라우팅))
- 프로토콜 - 포트: HTTP - 80
- 대상 그룹: 앞서 만들었던 대상 그룹을 선택한다.
언급하지 않은건 기본값으로 남겨둔다.
이제 요약을 잘 확인해 보고 이상이 없다면 생성을 완료한다.

AMI

AMI(Amazon Machin Image)는 인스턴스를 생성할 때 사용되는 이미지로, OS처럼 생각하면 될 것 같다. AMI가 있으면 다른 인스턴스를 생성해도 동일한 OS 및 환경을 구성할 수 있다. 우리는 이미 생성된 인스턴스가 있으므로, 그 인스턴스를 이용해 AMI를 생성할 것이다.

오토 스케일링은 인스턴스를 트래픽에 따라 자동으로 생성 및 삭제를 수행하는 기능으로, 이 기능을 사용하려면 시작 템플릿(Launch Template)이 필요하고, 이를 생성하려면 AMI가 필요하다. 우리가 새로운 인스턴스 만들 때 AMI를 선택하는 것처럼 자동으로 인스턴스 생성 시 사용될 AMI가 있어야 한다.

EC2 > 인스턴스로 이동하여 오토 스케일링을 적용할 인스턴스를 선택하고, 작업 > 이미지 및 템플릿 > 이미지 생성을 클릭한다.

이미지 이름: 자유롭게 입력하나, 어떤 이미지인지 잘 식별되도록 하자.
이미지 설명: 넘기지 말고, 어떤 목적으로 생성했는지 작성하자.
나머지는 기본값으로 두고 이미지 생성을 완료한다.

바로 생성이 완료되지는 않고, 몇 분 기다리다보면 사용 가능이라고 상태가 뜬다.

시작 템플릿

우리는 인스턴스를 생성할 때 AMI 선택 외에도 인스턴스에 관한 스펙(인스턴스 유형, 네트워크 설정 등)을 설정한다. 오토 스케일링으로 만들어질 인스턴스의 스펙은 시작 템플릿(Launch Template)을 통해 설정된다.

EC2 > 시작 템플릿으로 이동하여 시작 템플릿 생성을 클릭한다.

시작 템플릿 이름: 자유롭게 입력
템플릿 버전 설명: 보통 애플리케이션 이름과 함께 템플릿(Template)을 같이 적어주는 것 같다 (예시: HelloWorld Web Server Template)
애플리케이션 및 OS 이미지: 내 AMI > 내 소유 > 앞서 생성한 AMI 선택
인스턴스 유형: 애플리케이션 스펙에 맞춰서 선택하기. 연습용이거나 작은 프로젝트라면 `t3.micro`나 `t3.small`로 충분하다(docker로 서버를 띄운다면 small 권장)
키 페어 이름: 시작 템플릿에 포함하지 않음
서브넷/가용 영역: 시작 템플릿에 포함하지 않음
방화벽(보안 그룹): 오토 스케일링을 적용할(현재 CI/CD 되고 있는) EC2 인스턴스와 동일한 보안 그룹을 선택한다.
고급 세부 정보 > 사용자 데이터: 여기에 Java17 및 CodeDeploy 에이전트 설치와 애플리케이션을 실행할 디렉토리를 생성하는 명령어를 작성한다. 이 과정에서 인스턴스의 AMI는 Ubuntu라서 이 OS에 맞춰서 명령어를 사용했다. (AMI에서 하는 것이 더 적절해 보이는데 일단 여기에서)
```
#!/bin/bash
sudo apt update -y
sudo apt install -y openjdk-17-jdk

sudo apt install ruby-full
sudo apt install wget 
cd /home/ubuntu
wget https://bucket-name.s3.region-identifier.amazonaws.com/latest/install
chmod +x ./install
sudo ./install auto

mkdir -p /home/ec2-user/hello
```
언급하지 않은 나머지는 기본값으로 두고 생성을 완료한다.

오토 스케일링 그룹(ASG)

AWS ASG는 인스턴스를 그룹 단위로 관리하며, 트래픽 변화에 따라 스케일링 정책을 기반으로 자동으로 인스턴스 수를 증가시키거나 감소시킬 수 있다.

EC2 > Auto Scaling 그룹으로 이동, Auto Scaling 그룹 생성을 클릭한다.

1단계: 시작 템플릿 선택

이름: 자유롭게 입력
시작 템플릿: 앞서 생성한 템플리 선택

이후 다음 클릭

2단계: 인스턴스 시작 옵션 선택

VPC: EC2 인스턴스와 동일한 VPC 선택
가용 영역 및 서브넷: 자유롭게 선택. 모두 선택해도 상관없다. 단순하게만 보자면 많이 선택할 수록 가용성이 높아진다고 생각하면 될 것 같다. 최소한의 가용성을 고려했을 때 적어도 두 개는 선택하는 게 좋다.
가용 영역 배포: 균형 잡힌 최선 노력

이후 다음 클릭

3단계: 다른 서비스와 통합

로드 밸런싱: 기존 로드 밸런서에 연결
기존 로드 밸런서에 연결: 로드 밸런서 대상 그룹에서 선택
기존 로드밸런서 대상 그룹: 앞서 만든 대상 그룹 선택
상태 확인: Elastic Load Balancer 상태 확인 켜기 활성화
- 로드 밸런서가 인스턴스의 상태를 확인하고, 문제가 있는 인스턴스가 있으면 오토 스케일링이 이를 확인하고 인스턴스를 교체함

4단계: 그룹 크기 및 크기 조정 구성

원하는 용량(Desired capacity): 1 (상황에 맞춰서 진행, 여기서는 간단히 기본값으로 진행)
- 생성 시에 만들어지는 인스턴스 개수로, ASG는 이 수를 유지하려고 한다.
- 1로 설정한 경우를 예시로 보자. 실행되고 있는 한 개의 인스턴스가 예상치 못하게 종료되면, 원하는 용량값인 1을 유지하기 위해 ASG가 한 개를 새롭게 생성한다.
- *원하는 최소 용량 ≤ 원하는 용량 ≤ 원하는 최대 용량
원하는 최소 용량: 1 (상황에 맞춰서 진행)
- 스케일링 정책이 설정된 경우, 그룹의 원하는 용량을 이 값보다 더 작게 감소시키지 못함
원하는 최대 용량: 2 (상황에 맞춰서 진행)
- 스케일링 정책이 설정된 경우, 그룹의 원하는 용량을 이 값보다 더 크게 증가시키지 못함
Automatic scaling: 크기 조정 정책 없음
- 이 기능이 실제로 "오토 스케일링"이라고 부르는 부분이다. 지금은 정책 없음을 선택해서 ASG가 트래픽 변화에 따라 자동으로 스케일링 할 수 없다. 우리가 수동으로 원하는 용량을 변경하여 그룹 크기를 변경해야 한다. 따라서 `원하는 최소 용량`으로만 유지된다.
- 지금은 인스턴스 개수가 유지만 되도록 정책 없음을 선택했다.
인스턴스 유지 관리 정책: 정책 없음

나머지는 손대지 않고 다음으로 넘어간다.

5단계: 알림 추가

이 기능을 사용하려면 AWS의 다른 기능도 설정해야 해서 이 글에서는 넘어간다.

6단계: 태그 추가

이 단계도 그냥 넘어가도 된다. 태그를 설정하면 새로 생성되는 인스턴스의 이름을 지정할 수 있다. 보통 키는 `Name`을 유지하고 값에 애플리케이션/프로젝트 이름을 넣는 것 같다.

7단계: 검토

설정값들을 마지막으로 확인하고 생성을 완료한다.

ASG 생성이 완료되면 원하는 용량을 유지하기 위해 새 인스턴스를 생성한다. → 지금까지의 과정을 통해 생성된 인스턴스는 총 2개(이전 글에서 처음에 1개만 생성했다면)

CodeDeploy

CodeDeploy도 수정해야 한다. 우선 CodeDeploy의 IAM 역할부터 수정한다.

IAM 역할 - 권한 추가

IAM > 역할로 이동해서 전에 CodeDeploy를 위해 생성한 IAM 역할을 클릭한다. 이전 글에서는 `CodeDepoyServiceRoleForEC2`라는 이름으로 생성했다. 이동한 화면에서 권한 > 권한 추가 > 인라인 정책 생성을 클릭한다.

정책 편집기에서 JSON을 선택하고 아래와 같이 작성한다. (시작 템플릿으로 ASG을 생성한 경우, 다음 권한들이 필요함)

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "VisualEditor0",
			"Effect": "Allow",
			"Action": [
				"iam:PassRole",
				"ec2:CreateTags",
				"ec2:RunInstances"
			],
			"Resource": "*"
		}
	]
}

작성 후 다음으로 넘어가고, 권한 추가를 완료한다.

CodeDeploy 배포 그룹 편집

CodeDeploy > 애플리케이션 > 앞서 생성한 애플리케이션(SpringBootApp) > 앞서 생성한 배포 그룹(production)까지 이동하자. 이동한 화면에서 편집을 클릭한다.

이동하면 이전에 배포 그룹을 생성했을 때 보았던 화면이 나온다.

배포 유형: 블루/그린 (현재 위치 → 블루/그린)
환경 구성: Amazon EC2 Auto Scaling 그룹 자동 복사
ASG 선택: 앞서 생성한 ASG 선택
배포 설정 - 새 배포가 생성되면 바로 트래픽을 라우팅 하고, 기존 인스턴스는 15분 후 종료되게 설정한다.
- 트래픽 재 라우팅: 즉시 트래픽 라우팅
- 배포 성공 후 원본 환경 인스턴스 종료 여부 및 종료 전 대기 시간 선택: 배포 그룹의 원본 인스턴스 종료
- 일: 0
- 시간: 0
- 분: 15
- 배포 구성: CodeDeployDefault.AllAtOnce
로드 밸런서 유형: Application Load Balancer 또는 Network Load Balancer 활성화
대상 그룹 선택: 앞서 생성한 대상 그룹 선택

변경 사항 저장을 클릭하여 편집을 완료한다.

이제 CodeDeploy를 사용하여 ASG의 EC2 인스턴스에 배포할 수 있다!

블루/그린 무중단 배포 과정 정리

새로운 버전을 배포하기 전 상태

인스턴스 총 개수: 직접 생성한 EC2 인스턴스 1개(A라고 지칭) + ASG로 생성된 EC2 인스턴스 1개(B라고 지칭)
- 이 둘을 Blue 그룹이라고 하자.

배포 과정(단순하게 표현함, 실제로는 더 많은 단계가 있음)

코드 변경 사항이 발생하여 GitHub 레포지토리에 commit/push
GitHub Actions에서 감지(push trigger) → 배포 스크립트(.github/workflows/deploy.yml) 실행
GitHub Actions에서 CI를 진행하고 CodeDeploy를 통해 CD 진행
CodeDeploy를 통해 다음의 과정이 일어난다.
1. Green 그룹 생성: 2개의 인스턴스를 새롭게 생성
  - 이때 ASG 그룹이 하나 더 늘어나고, 인스턴스 목록도 보면 2개에서 3개로 늘어나있는 것을 볼 수 있다.
2. Green 그룹에 새로운 버전의 배포를 진행
3. Green 그룹으로 트래픽 라우팅
4. 배포가 성공하고 15분 후에 Blue 그룹 제거
  - 새로 생겼던 ASG 그룹이 유지되고, 기존 그룹은 제거된다. (그룹 수 다시 1개)
  - ASG로 인해 생겼던 기존 인스턴스도 제거되고, 새로운 인스턴스가 유지된다. (인스턴스 수 다시 2개: 수동 생성했던 인스턴스 1 + 지금 새로 생긴 인스턴스 1)
배포 완료

후기

어느 리소스를 생성하든, 그 리소스가 명시되도록 이름을 잘 짓는게 중요하다. 어떤 목적으로 리소스를 생성했는지 설명을 잘 작성하는 것도 무척 중요하다.

AWS 리소스를 생성하는 과정에서 어떤 옵션을 선택할 때 이 옵션이 무엇인지 작게 설명이 쓰여있는데, 잘 읽어보면 꽤나 도움이 된다. (사실 아리송할 때가 더 많은 것 같기도... 이때 이해 못 해서 공식 문서를 찾아봐도 궁금증이 완전히 해결되는 경우는 아직까지 많지 않은 듯)

[TIL / AWS] SpringBoot 서버리스로 배포하기: ECR + Fargate(ECS) + ALB + Private Link

jaamong — Thu, 7 Aug 2025 23:54:48 +0900

공유도 있지만, 기록이 더 큰 목적... Windows 11, Gradle/SpringBoot.

AWS에서 "아.. Fargate 좋은데... 안쓰나... 진짜 좋은데..." 라고 계속 홍보하는 것 같아서 이번 프로젝트에서는 도대체 얼마나 좋길래? 하고 사용해봤다.

후기! EC2 보다 비용이 좀(꽤) 나가지만, 서버 설정이 편리하다. 서버 설정 자체는 신경을 안쓰게 되긴하는데 인프라는 건들게 너무... 많다...

자세히는, 퍼블릭 서브넷에 배포한다면 정말 금방 끝낼 수 있다. 하지만 프라이빗 서브넷에 배포한다면 많은 설정들이 기다리고 있다. (이때 배포하는 과정에서 Private Link 관련으로 삽집을 많이해서 기록용으로 작성하게 됐다)
불편한 점이 꽤 있다. EC2로 배포하면 당연했던 것들이 서버리스라서 그런지 안되는 게 꽤 있다. 그 중 하나는 보통 private subnet에 위치한 RDS에 EC2를 터널링으로 사용하여 접근했는데, Fargate는 이게 안된다.(서버 접근할 때 사용하는 키페어가 없음) 그래서 Bastion Host 용도로 nano 인스턴스 타입의 EC2를 하나 생성했다
로그 설정이나 확인이 EC2보다 어려운 것 같다.

컨테이너 오케스트레이션 목적이 크지 않다면, 다음에도 Fargate를 또 쓸지는 모르겠다.

사전 준비

Docker 계정
AWS CLI 설치
AWS CLI를 사용할 수 있는 AWS IAM 계정 (충분히 권한이 있는지)

Fargate

Fargate는 서버리스 컴퓨팅 서비스로 컨테이너를 실행하기 위해 사용할 수 있다. ECS와 함께 사용해야 한다(단독 사용 X).
- ECS는 Elastic Container Service의 줄임말로, 이름대로 완전 관리형 컨테이너 오케스트레이션 서비스이다. 쿠버네티스가 아닌 도커 컨테이너 관리를 위한 서비스이다. 쿠버네티스는 EKS라고 따로 있다.
Fargate는 EC2와 달리 사용자가 서버나 클러스터를 관리할 필요가 없지만, 실제로는 EC2 위에서 실행된다.
EC2와 동일 스펙으로 두고 보았을 때 요금이 더 비싸다. (솔직히 EC2에 비해 조금... 부담될 수도 있다.)
CloudWatch와 자동 연동 된다.
리소스(Task) 생성 시 VPC 내부 서브넷에 위치한다.

ECR

ECR은 컨테이너 이미지를 저장 및 관리할 수 있는 서비스이다. 여기에 빌드한 Docker 이미지를 올려서 ECS(Fargate)를 통해 배포할 수 있다.
컨테이너 이미지 레이어를 S3에 저장한다.
VPC 밖에 위치한다.
- 따라서 Fargate(VPC 내부)에서 ECR(S3)에 저장된 컨테이너 이미지를 가져오려면 인터넷 통신이 필요함
  - Fargate의 위치가 퍼블릭 서브넷이고, 생성 시 공인 IP가 자동 할당되도록 설정했다면 문제없음
  - 프라이빗 서브넷이면 공인 IP가 할당되어도 인터넷 통신이 불가능하므로 ECR(S3)에서 컨테이너 이미지를 가져올 수 없음 → NAT Gateway 사용 또는 Private Link 구성으로 해결해야 함

Private Link

VPC 엔드포인트, Gateway Endpoints(S3 또는 DynamoDB)를 사용해서 VPC 밖에 있는 두 서비스 사이에서 인터넷이 아닌 사설(private) 통신이 가능하도록 하는 서비스
둘 중에 무엇을 선택할지는 비용을 따지는 편. 발생하는 비용은 각자 서비스의 데이터 처리량 등을 고려하여 계산.

Fargate로 SpringBoot 애플리케이션 배포하기

Dockerfile 작성하기
도커 이미지 빌드 및 도커 허브에 push (이미지 이름 기억해 두기)
ECR에서 Private Repository 생성
생성한 레포지토리를 선택하고 푸시 명령 보기 클릭, 가이드 보면서 순차적으로 진행
- ECR 레지스트리에 Docker 클라이언트 인증 시 AWS CLI default 프로필 외에 다른 프로필 사용 시 아래와 같이 진행
```
aws ecr get-login-password --region ap-northeast-2 --profile {profile_alias}| docker login --username AWS --password-stdin {account_id}.dkr.ecr.ap-northeast-2.amazonaws.com
```
- 태깅할 때 태그는 앞으로 생성될 이미지 태그와 겹치지 않게 고유한 태그로 생성할 것
클러스터 생성: 클러스터는 서비스나 태스크의 논리적인 그룹이다.
1. ECS > 클러스터 > 클러스터 생성
2. 인프라: AWS Fargate
3. 클러스터 이름 작성이랑 인프라 선택만 하고 완료하기
작업(Task) 정의: Task에 필요한 명세를 정의한다. Amazon ECS에서 Docker 컨테이너를 실행하려면 작업 정의(Task Definition)가 필요함. 이전에 생성한 도커 이미지를 참조하는 작업 정의를 생성한다.
- ECS > 태스크 정의 > 새 태스크 정의 생성 > 새 태스크 정의 생성
  - 태스크 정의 패밀리: 고유한 이름 지정
  - 인프라
    - 시작 유형: AWS Fargate
    - 태스크 역할
      - 태스크 역할: 건들지 않음
      - 태스크 실행 역할: Amazon ECS를 처음 사용하는 경우 `ecsTaskExcutionRole IAM` 역할이 존재 X. 이 경우는 Task execution role 설정에서 Create new role을 선택하면 자동으로 `ecsTaskExcutionRole` IAM 역할이 생성됨.
    - 애플리케이션에 필요한 사양에 맞춰서 진행
  - 컨테이너
    - 이름: 임의 지정
    - 이미지 URI: ECR에 올린 도커 이미지의 URI로 ECR > 프라이빗 레지스트리 > 리포지토리 > {생성한 리포지토리}에서 이미지 URI를 복사할 수 있음
    - 필수 컨테이너: 예
    - 프라이빗 레지스트리: 비활성화
    - 포트 매핑: 여기에서는 스프링부트의 8080번 포트로 지정. 이 부분은 각자의 환경에 맞춰 설정. 로드밸런싱을 사용한다면 여기에서 로드밸런서의 요청을 받을 포트를 설정.
  - 로깅
    - `awslogs-region`을 잘 확인하고, 나머지는 위와 같이 설정한다.
  - 나머지는 기본 상태로 두고 작업 정의를 완료한다.
ECS 작업 IAM 역할 수정: 앞 단계에서 자동 생성된 ECS 작업의 IAM 역할인 `ecsInstanceRole`에 `CloudWatchLogsFullAccess`를 추가
1. IAM > 역할 > ecs 검색 > `ecsInstanceRole` 선택
2. 권한 탭 > 우측 권한 추가 메뉴 > 정책 연결 클릭
3. 검색창에서 `CloudWatchFullAcess` 검색 > ` CloudWatchFullAcessV2` 선택 > 권한 추가 클릭
4. 추가된 정책 확인
ALB 구성 및 생성: private subnet에 위치한 ECS와 연결하여 외부 트래픽 진입점이 될 ALB를 생성한다.
- 대상 그룹 생성
  1. EC2 > 대상 그룹 > 대상 그룹 생성
  2. 대상 유형: IP address
  3. 타겟 그룹 이름: 자유롭게 설정(보통 tg를 이름에 넣어서 대상 그룹임을 명시하는 편)
  4. 프로토콜 : 포트: HTTP : 8080(ALB가 요청을 보내줄 포트, 배포할 컨테이너(ECS)의 실행 포트로 입력. 모르겠다면 애플리케이션의 실행포트로 입력)
  5. VPC: 로드 밸런서를 호스팅 할 VPC 선택(ECS가 있는 VPC로)
  6. 상태 검사: 애플리케이션에 헬스 체크 API가 있다면 여기에 입력
  7. 나머지는 기본값으로 놔두고 다음 클릭
  8. 대상 등록: 아무것도 건들지 않고, 대상도 등록하지 않고 생성 완료하기. 나중에 ECS가 생성될 때 생성된 태스크가 자동으로 등록됨.
- ALB 생성
  1. EC2 > 로드 밸런서 > 로드 밸런서 생성
  2. ALB 생성
  3. 로드 밸런서 이름: 자유롭게 설정(tg처럼 이름에 alb를 추가해서 명시하는 편)
  4. 체계(schema): 인터넷 경계(internet-facing)
  5. 네트워크 매핑: 대상 그룹과 동일한 VPC
    - 선택 후, 가용 영역 및 서브넷: 2개 이상 선택
  6. 보안 그룹: 이 ALB를 위해 생성해 둔 것이 없다면 새롭게 생성. 보안 그룹은 아래 조건을 만족하면 됨.
    - 새로 생성 시 아웃바운드는 건들지 않고, 외부 트래픽을 받을 수 있도록 인바운드만 설정
      - 유형: HTTP
      - 포트: 80
      - 소스: 0.0.0.0/0
  7. 리스너 및 라우팅: 외부 트래픽을 어떤 프로토콜과 포트로 받을지 결정하여 이 통로만 열어두고(리스너) , 받은 요청을 어디로 보낼지(라우팅) 설정
    - 프로토콜: HTTP
    - 포트: 80
    - 대상 그룹: 방금 생성한 대상 그룹 선택. 여기로 요청이 라우팅 된다.
    - 요약 정보를 확인하고, 모두 맞다면 완료하기
ECS 서비스 생성: Amazon ECS를 사용하여 Amazon ECS 클러스터에서 지정된 작업 정의 인스턴스를 동시에 실행하고 관리할 수 있다. 이를 서비스라고 한다.
1. ECS > 생성한 클러스터 선택 > 서비스 탭 > 생성 버튼 클릭
2. 서비스 세부 정보 설정
3. 환경 > 컴퓨팅 구성
  - 컴퓨팅 옵션: 시작 유형
  - 시작 유형: FARGATE
  - 플랫폼 버전: LATEST
4. 배포 구성
  - 스케줄링 전략: 복제본
  - 원하는 태스크: 서비스(여기서는 개발하는 프로덕트를 의미) 상황에 맞게 (여기서는 1개만 함)
    - Task: 특정 애플리케이션 기능을 수행하는 하나 이상의 컨테이너
    - Service: 동일한 다수의 Task 그룹
  - 나머지는 기본값으로 두기
5. 네트워킹 설정
  1. VPC: VPC는 이미 생성된 것을 사용하거나 다른 서비스/프로젝트와 구분 지어 사용하고 싶다면 새롭게 생성. 잘 모르겠다면 default VPC 사용도 상관 X.
  2. 서브넷: 프라이빗 서브넷(private subnet)으로 선택.
    - 퍼블릭 서브넷(public subnet)도 가능함. 이 경우 다음을 참고.
      - ALB & VPC 엔드포인트나 NAT 없이도 외부 트래픽을 받을 수 있음
      - 퍼블릭 IP 옵션을 활성화 → 하나의 퍼블릭 IP에 대해서 시간당 0.005 USD의 요금이 부과됨
      - ALB와 VPC 엔드포인트 설정이 별도로 필요 없음
      - 퍼블릭 서브넷에 두면 보안 및 확장성 측면에서 좋지 않음
  3. 보안 그룹: 위에서 생성한 ALB를 고려해서 ECS를 위해 미리 만들어둔 보안 그룹이 없다면, 새로 생성하기
    1. 보안 그룹 이름: 여기에서도 sg를 이름에 추가해서 보안 그룹임을 명시하는 편
    2. 설명: 보통 어떤 목적의 보안 그룹인지 작성하는 편
    3. 인바운드 규칙
      1. 유형: 사용자 지정
      2. 포트 범위: 8080 (대상 그룹에서 입력한 포트와 동일하게)
      3. 소스: ALB를 위해 만들었던 보안그룹을 선택 (ALB를 통해서만 외부 트래픽이 들어올 수 있게 됨)
6. 로드 밸런싱
  1. 로드 밸런싱 사용: 활성화
  2. VPC: 로드 밸런싱이 위치한 VPC로 선택
  3. 로드 밸런서 유형: ALB
  4. Application Load Balancer: 기존 로드 밸런서 사용
  5. 컨테이너: 기본적으로 잘 선택되어 있을 테니, 가만히 내버려 두거나 아래를 참고해서 틀렸다면 수정하기
    - 포트가 `8080:8080` 이렇게 되어 있을 텐데, 이런 의미다. `{컨테이너가 실행되는 호스트 머신의 포트}:{컨테이너 내부 포트}` → a:b 라면 a번 포트를 컨테이너의 b 포트로 연결하여 외부에서 a번 포트로 접근하면 컨테이너의 b번 포트로 연결됨(포트 포워딩)
  6. 로드 밸런서: 위에서 생성했던 로드 밸런서 선택
  7. 리스너: 8080-HTTP (대상 그룹에서 입력한 포트와 동일하게)
  8. 대상 그룹: 기존 대상 그룹 사용
  9. 대상 그룹 이름: 위에서 생성한 대상 그룹 선택
  10. 상태 확인 경로: 헬스 체크 API 있으면 작성
7. 나머지는 기본값으로 놔두고 완료하기
Private Link: 이대로 배포하면 ECR에서 이미지를 가져올 수 없다고 하는 통신/연결 에러가 발생할 것이다. 해결을 위해 다음 설정을 진행한다. 여기서는 3개의 VPC Endpoint(Interface형 VPC Endpoint 개당 0.013 USD / hour)와 S3 Gateway Endpoint(무료)를 생성한다. 참고로, 엔드포인트 사용료 외에도 데이터 처리량에 따른 요금이 추가로 부과된다. 자세한 건 공식 문서 참고하기!
- VPC Endpoint
  1. VPC > PrivateLink 및 Lattice > 엔드포인트
  2. 엔드 포인트 생성 클릭
  3. 유형: AWS 서비스
  4. 서비스 > 검색창: `ecr`
    - 검색 시 `ecr.api`와 `ecr.dkr`이 나타남. 모두 필요하지만, 한 번에 여러 개 생성 불가능. 우선 둘 중 하나 선택하여 진행
  5. 네트워크 설정: ECS가 있는 VPC 선택
  6. 서브넷: ECS가 있는 서브넷
  7. 보안그룹: VPC 엔드포인트용 보안 그룹 생성
    1. EC2 > 보안 그룹 > 보안 그룹 생성 - 인바운드 규칙만 추가
    2. 유형: HTTPS
    3. 소스 유형: 사용자 지정
    4. 소스: ECS가 속한 VPC의 IP 범위 (IPv4 CIDR)
  8. 정책: 전체 액세스
  9. 완료 (다음 셋 중 하나라도 안 하면 배포 실패)
    - 동일한 과정으로 총 3번 반복: `api`, `dkr`, `logs`
- VPC Gateway
  1. VPC 엔드포인트의 3번까지 동일
  2. 서비스 > 검색창: `s3`
    - 유형이 `Gateway`인 항목으로 선택
  3. 네트워크 설정: ECS가 있는 VPC 선택
  4. 라우팅 테이블: ECS가 있는 서브넷과 연결된 라우팅 테이블 선택
  5. 정책: 전체 액세스
  6. 완료
드디어 모든 설정 끝!!! ECS 배포 상태를 확인해 보기
- ECS > 클러스터 > 생성한 클러스터 클릭 > 서비스 탭 > 생성한 서비스 선택 > 배포 탭 클릭
- 배포가 정해진 횟수만큼 실패하다 보면, 자동으로 배포가 실행되지 않는다. 이때는 서비스 업데이트를 클릭.
  - 배포 구성 > 새 배포 강제 적용: 활성화
  - 나머지는 손대지 말고 업데이트 완료하기
- 이제 배포가 진행된다.
- 배포가 성공했다면, ALB의 DNS를 통해 접근할 수 있다. (HTTPS 미적용 상태임을 잊지 말기~)
  - 선택된 서비스에서 구성 및 네트워킹 > DNS 이름이 해당 정보이다.

CoudWatch

별도로 설정을 안 했으면 기본 옵션으로 되어있다. 기본적으로 CloudWatch가 ECS에서 수집하는 지표는 ECS 클러스터 내 전체 자원의 평균 CPU 사용률, 평균 메모리 사용률 등 간단한 지표만 제공한다. 클러스터 수준의 지표만 수집하므로 세부 수준의 지표는 모니터링할 수 없다.

Container Insight를 사용하면 클러스터 내에서 더 세부적인 지표를 수집할 수 있다. 두 가지가 있다.

일반 컨테이너 인사이트: ECS 클러스터 및 ECS 서비스 수준에 대해 지표를 수집
- 일반 CloudWatch 지표 수집 비용과 동일. 수집한 지표 당 0.30 USD /month
향상된 관찰 기능을 갖춘 컨테이너 인사이트: ECS 클러스터, ECS 서비스, ECS 태스크 정의, ECS 태스크, 실행 중인 컨테이너 수준에서 더 많은 지표를 수집
- 수집한 지표 당 0.07 USD / month

후자가 더 많은 지표를 수집하여 자세한 정보를 알 수 있긴 하지만, 지표 수가 많을수록 비용이 많이 부과되므로 잘 생각해 보고 선택해야 한다. 또한 서비스나 태스크는 트래픽 상황에 따라 얼마든지 증가할 수 있는데, 지표도 그만큼 많이 수집되므로 비용이 생각보다 많이 부과될 수도 있다. 주의하자!

비용 관련 공식 정보: https://aws.amazon.com/ko/cloudwatch/pricing/

CI/CD 구축하기: GitHub Actions (OIDC) + Amazon S3 + Amazon CodeDeploy

jaamong — Mon, 28 Jul 2025 20:01:53 +0900

AWS EC2 인스턴스(Ubuntu 24.04) 한 대에 배포되고 있는 Gradle/SpringBoot 서버에 대해서 OIDC를 이용해서 CI/CD를 구축해 보는 글입니다. EC2 인스턴스 생성은 다루지 않습니다.

⏭️다음 글: CI/CD에 블루-그린 무중단 배포 적용하기: AWS ELB, AWS Auto Scaling Groups(ASG)

⭐항상 AWS 리소스를 다룰 땐 참고하고 있는 글이 최신 버전인지 확인하기⭐

작성 계기

GitHub Actions를 CI 툴로 사용하는 대부분의 소개글은 GitHub Actions에서 AWS로 접근하기 위해 IAM 액세스 키를 많이 사용한다. 이때 여러 가지를 고려했을 때 IAM 액세스 키보다는 OpenID Connect(OIDC) 사용을 더 권장한다고 한다. 그래서 도입하기 위해 찾아보면, OIDC를 구성하는 글과 이를 CI/CD에 적용하는 글은 다 별개로 작성되어 있어 답답했다. 그래서 그냥 내가 해보면서 성공하면 작성하자!라는 생각으로 시작했고, 다행히 성공해서 이렇게 쓰게 되었다.

사전 준비

AWS 루트 계정 말고, 필요한 권한을 다 갖고 있는 IAM 사용자; 개인 AWS 계정이더라도, IAM 사용자를 생성해서 진행하자.
- 이 과정을 위해 IAM 사용자에게 어떤 권한을 부여해야 할지 모르겠고, 찾기도 힘들다면 `AdministratorAccess` 정책(policy)을 갖게 하자. 거의 대부분의 권한을 갖고 있다.
CI/CD 배포 대상인 EC2 인스턴스와 프로젝트 실행에 필요한 언어 설치
- EC2 인스턴스의 OS(AMI)는 Ubuntu 24.04
- VPC나 서브넷(subnet)은 AWS에서 기본적으로 제공해 주는 것을 사용해도 문제없다. 직접 생성하고 사용하려면 그것 자체로 포스트 하나가 나오므로.. 그냥 디폴트 VPC와 서브넷을 사용하자.
- 여기서는 EC2 인스턴스에 Java 17 / SpringBoot / Gradle 프로젝트를 운영한다. 하지만 개발 언어나 프레임워크가 무엇인지는 크게 중요하지 않다.
- 언어 설치는 사실 미리 해두지 않아도 괜찮은 것 같다. 편한대로 하면 된다.
배포할 프로젝트가 올라가있는 GitHub 레포지토리
- 레포지토리가 속한 조직(organization)과 어떤 브랜치를 대상으로 배포할지 미리 알아두기!
  - 개인 계정인 경우, 별도로 생성해둔 조직이 없다면 보통 계정명이 조직명이 된다.
  - 브랜치도 특별히 정해진 브랜치 배포 규칙이 없다면 보통 `main` 브랜치가 된다.
프로젝트에 미리 헬스체크 API 만들어두기 (당장 필요하진 않지만, 다음 글에서 필요)
- HTTP 메소드는 `GET`, 반환은 `200 OK`만 해줘도 충분하다.

본론

전체 흐름

CI/CD 파이프라인에서 GitHub Actions는 CI를 담당한다. 개발자가 GitHub에 push 등의 지정한 동작을 수행하면 GitHub Actions이 트리거 되어 `.github/workflows/{수행할_파일}.yml`에 적힌 내용을 수행한다. 이 파일은 다음 워크플로우를 수행한다.

[Build] 애플리케이션 빌드 (이 결과물을 아티팩트라고 함)
[Build] 아티팩트를 `@actions/upload-artifact`를 이용하여 GitHub에 업로드
[Deploy] GitHub에 업로드한 아티팩트를 `@actions/download-artifact` 다운로드
[Deploy] GitHub Actions OIDC를 이용하여 AWS credentials 설정
[Deploy] 아티팩트 패키징(압축) 및 S3에 업로드
[Deploy] CodeDeploy를 이용하여 S3에 업로드된 패키징을 EC2 인스턴스에 배포
[Deploy] 배포 완료 대기

EC2 보안그룹(Security Group) 설정

EC2 인스턴스가 준비되었다면, EC2 보안그룹을 설정해보자. 이미 해두었을 것 같은데, 혹시 모르니 추가.

AWS는 보안그룹에 대해 기본적으로 아웃바운드는 다 허용하고 인바운드는 다 막아둔다. 즉, 서버로 들어오는 요청은 다 막고, 나가는 것은 다 허용한다는 뜻이다. 따라서 필요한 요청은 받을 수 있게 적절하게 인바운드 규칙을 설정해야 한다.

EC2 메뉴 하위에 위치한 보안그룹을 찾아서 이동한다.

EC2 인스턴스를 생성할 때 보안그룹을 새로 생성하는 옵션을 선택했다면, `launch-wizard-1` 이름을 가진 보안그룹이 있을 것이다. 이것을 선택하고, 인바운드 규칙 편집을 클릭한다.

다음과 같이 설정하고 마치면 된다.

인스턴스 생성 시 발급한 `.pem` 파일로 EC2에 접근하려면 SSH를 열어야 한다. 알고 있겠지만, 소스를 저렇게 `0.0.0.0/0`으로 다 열어두는 것보단 접속하는 곳의 IP만 지정하는 것이 보안상 좋다.
여기서는 스프링 부트 애플리케이션을 실행하므로, `사용자 지정 TCP`로 유형을 선택하고 포트를 `8080`으로 입력한다. 8080번 포트가 아닌 다른 포트로 애플리케이션을 실행한다면 그 포트를 입력하면 된다.
Nginx 같은 걸로 HTTP 80 요청을 받아서 애플리케이션에게 전달하는 상황이 아니라서, HTTP 80은 추가하지 않았다.

이제 보안그룹 설정은 완료됐다.

EC2 인스턴스에 CodeDeploy의 접근을 위한 IAM 역할(role) 생성 및 부여하기

AWS 리소스와 외부에서 서로 접근하듯이, AWS 리소스끼리도 서로 접근할 수 있다. 이를 위해 적절한 권한을 가진 IAM 역할이 리소스에게 부여되어야 한다.

여기서는 다음을 고려해야 한다.

EC2 인스턴스 to S3 버킷에 대한 접근 권한
EC2나 온프레미스 환경에서 CodeDeploy를 사용하려면 CodeDeploy 에이전트가 필요하다. 그리고 이 에이전트가 필요로 하는 권한이 있다.

이제 IAM 역할을 생성하고 부여해보자.

IAM 역할 생성

IAM 메뉴 하위에 있는 역할을 클릭하여 이동한다. 이동한 대시보드에서 역할 생성을 클릭한다.

1단계: 신뢰할 수 있는 엔터티 선택에서 AWS 서비스를 선택하고, 사용 사례로 EC2를 선택한다. 선택하면 다양한 사용 사례가 아래 나열되는데, EC2 만 적힌 것을 선택하면 된다. 그리고 넘어간다.

2단계: 권한 추가의 검색창에서 다음 두 개를 검색해서 추가한다.

AmazonEC2RoleforAWSCodeDeploy: 이 권한은 EC2가 S3 버킷에 제한적으로 접근할 수 있도록 하며, EC2에 설치된 CodeDeploy 에이전트에게 필요하다.
AmazonS3ReadOnlyAccess: 이 권한은 모든 S3 버킷에 접근할 수 있도록 한다. 위 권한만을 가지고 S3 버킷에 접근할 수 있지만, CodeDeploy가 사용할 S3 생성 시 태그 설정(UseWithCodeDeploy=true)이 필요하다. 일단 이 권한을 추가해서 넓게 접근할 수 있도록 한다.
- 사실 이 부분을 CI/CD 구축한 후에 알아서 일단 이 버전으로 작성한다.

권한 경계 설정은 손대지 않고 다음으로 넘어간다.

3단계: 이름 지정, 검토 및 생성에서 이 역할의 이름과 설명을 작성한다. 이름은 어떤 역할을 수행하는지 나타낼 수 있도록 명확하게 작성한다. 나머지는 그대로 두고, 역할 생성을 클릭하여 완료한다.

IAM 역할 부여

이제 EC2 인스턴스 대시보드로 돌아오자.

CI/CD를 적용할 인스턴스를 선택하고, 작업 > 보안 > IAM 역할 수정을 클릭한다.

방금 만든 IAM 역할을 선택하고 IAM 역할 업데이트를 클릭하여 완료한다.

EC2 인스턴스 태그(tag) 설정

CodeDeploy로 배포를 할 때는 이 리소스에게 정보를 제공해줘야 한다. 여기서

태그는 CodeDeploy 배포 그룹에서 배포할 EC2 인스턴스를 식별하고 타겟팅하는 용도로 사용된다. 또한 태그를 이용해서 `prod`나 `dev` 등의 배포 환경을 식별할 수도 있다.

다시 인스턴스 대시보드로 와서, 배포 대상인 인스턴스를 선택하자. 그리고 아래 태그 탭에서 태그 관리를 클릭한다.

`Environment` 키에는 배포 환경을 입력하고, `Application` 키는 원하는 대로 입력해도 된다. 입력하고 잘 기억해 두자. (두 키 값의 이름도 잘 기억만 해두면 상관없으니, 편한 대로 입력해도 상관없다)

CodeDeploy 에이전트 설치 (Ubuntu 서버 버전)

CodeDeploy를 사용하여 EC2에 배포하려면 위 에이전트를 설치해야 한다. 터미널에서 아래 명령어로 EC2에 접속하자.

ssh -i {ec2 생성 시 발급받은 .pem이 위치한 경로 + 이름}.pem ubuntu@{ec2 퍼블릭 DNS 주소}

# 예시 1) pem 키가 위치한 곳에서 진행중일때
ssh -i example_key.pem ubuntu@ec2-dns-address  

# 예시 2) pem 키가 위치한 곳이 아닐때 (Windows cmd 이용 시)
ssh -i C:\Users\user\Desktop\...\example_key.pem ubuntu@ec2-dns-address

배포 대상인 EC2 인스턴스의 AMI가 Ubuntu 이므로, ` ubuntu`가 기본 사용자 이름이 된다. AMI에 따라 기본 사용자 이름이 다르므로 여기를 참고.

접속을 성공했다면 아래 명령어를 순서대로 입력하여 최신 버전의 CodeDeploy 에이전트를 설치한다. 혹시 모르니 공식 문서를 참고하면서 진행하자.

sudo apt update
sudo apt install ruby-full
sudo apt install wget
cd /home/ubuntu
wget https://bucket-name.s3.region-identifier.amazonaws.com/latest/install
chmod +x ./install
sudo ./install auto

잘 진행되었다면 아래 명령어를 입력하여 실행 상태를 확인한다.

systemctl status codedeploy-agent

정상적으로 실행되고 있다면 아래와 같이 `active (running)`를 확인할 수 있다.

OIDC 설정 및 GitHub Actions OIDC를 위한 IAM 역할 생성

이제 OIDC 공급 업체를 등록하고 이 OIDC를 통해 GitHub Actions이 AWS 리소스에 접근할 수 있도록 역할을 생성 및 부여한다.

IAM > 제공업체로 이동하고 공급자 추가를 클릭한다.

ID 제공업체 추가 화면에서 아래와 같이 입력하고, 하단에 공급자 추가를 클릭한다.

공급자 유형: `OpenID Connect`
공급자 URL: `https://token.actions.githubusercontent.com`
대상: `sts.amazonaws.com`

IAM > 역할로 이동하고 역할 생성을 클릭한다. 1단계: 신뢰할 수 있는 엔터티 선택에서 웹 자격 증명을 선택한다.

선택하면 아래와 같은 화면이 나온다. 모두 입력하고 다음을 클릭한다.

ID 제공업체: 아까 추가한 OIDC 제공업체가 목록에 있을 것이다. 이것을 선택한다.
Audience: OIDC 제공업체 추가 시 입력한 `대상`을 선택한다.
GitHub organization: 배포할 레포지토리가 위치한 조직명을 입력한다. 조직을 만든 적이 없다면, 보통 GitHub `username`이 조직명이 된다.
GitHub Repository: 기본적으로 모두 허용인데(`*`), 보안상 타겟이 되는 레포지토리명을 입력하는 것이 좋다.
GitHub branch: 이것도 기본적으로 모두 허용이지만, 배포할 브랜치를 따로 입력하자.

2단계: 권한 추가에서 `AmazonS3FullAccess`, `AWSCodeDeployDeployerAccess`를 검색하여 추가한다.

AmazonS3FullAccess: 모든 버킷에 대한 전체 액세스를 제공한다.
AWSCodeDeployDeployerAccess: 개정을 등록하고 배포할 수 있는 액세스 권한을 제공한다.

3단계: 이름 지정, 검토 및 생성에서 역할의 이름과 설명을 입력한다.

1단계에서 지정했던 신뢰할 수 있는 엔터티 선택의 JSON이 아래와 같은지 확인하자.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::{aws_account_id}:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                },
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:{organization}/{repository}:ref:refs/heads/{branch}"
                }
            }
        }
    ]
}

그다음 추가한 정책들이 모두 포함되어 있는지 확인하고, 모두 문제가 없다면 완료하자.

CodeDeploy을 위한 IAM 역할 생성 및 CodeDeploy 생성

CodeDeploy IAM 역할 생성

이번에는 CodeDeploy를 위한 IAM 역할을 생성한다. 이전과 같이 역할을 생성하는 곳으로 이동하여 진행한다.

1단계: 신뢰할 수 있는 엔터티 선택에서 AWS 서비스를 선택한다. 사용 사례는 CodeDeploy를 선택하고 다음으로 넘어간다.

2단계: 권한 추가를 보면 자동으로 `AWSCodeDeployRole` 권한이 추가되어 있다. 다음으로 넘어가자.

3단계: 이름 지정, 검토 및 생성에서 역할의 이름과 설명을 입력하고 마친다.

CodeDeploy 생성

이제 CodeDeploy > 배포 > 애플리케이션으로 이동하자. 이동하면 대시보드에 있는 애플리케이션 생성 버튼을 클릭한다.

본인의 애플리케이션의 이름을 입력하고, 우리는 EC2 인스턴스에 배포할 계획이므로 컴퓨팅 플랫폼을 `EC2/온프레미스`로 선택한다. 그리고 생성 버튼을 클릭한다. 참고로 애플리케이션 이름은 GitHub Actions CI 단계에서 필요하므로 잘 기억해 두자.

이후 생성한 애플리케이션을 클릭하면 나오는 대시보드에서 배포 그룹 탭을 클릭한다. 여기에서 배포 그룹 생성을 클릭한다.

배포 그룹 이름을 원하는 대로 입력한다. 입력해 놓고 잘 기억해 두자. GitHub Actions CI 단계에서 필요하다.

서비스 역할은 방금 CodeDeploy 용으로 생성한 IAM 역할을 선택한다.

배포 유형과 환경 구성을 아래와 같이 선택한다. 이때 태그 그룹의 키와 값은 본인이 EC2 인스턴스에 추가한 태그의 키와 값과 동일해야 한다.

배포 유형: 현재 위치(In-place)
환경 구성: Amazon EC2 인스턴스
- 태그 그룹: EC2 인스턴스에 등록한 태그와 동일하게 설정

CodeDeploy 에이전트는 이미 설치했으므로 안 함을 선택한다. 배포 설정의 배포 구성은 `AllAtOnce`로 선택한다. 로드 밸런싱 활성화는 체크하지 않는다. 이제 배포 그룹 생성을 클릭하여 완료한다.

S3 버킷 생성 및 정책 설정

S3 버킷 생성

S3 서비스로 이동해서 버킷 만들기를 클릭한다. 그리고 다음과 같이 진행한다.

버킷 이름: 누군가가 쓰고 있는 이름은 사용할 수 없으므로, 전역적으로 식별되는 이름을 입력해야 한다.
- GitHub Actions에서 필요하니 이름을 기억해 둘 것
객체 소유권: ACL 비활성화됨(권장)
이 버킷의 퍼블릭 액세스 차단 설정: 모든 퍼블릭 액세스 차단
버킷 버전 관리: 활성화
기본 암호화 - 암호화 유형: Amazon S3 관리형 키(SSE-S3)를 사용한 서버 측 암호화
기본 암호화 - 버킷 키: 활성화

위에서 언급되지 않은 나머지 요소들은 초기 상태 그대로 놔둔다. 이제 버킷 만들기를 클릭하여 완료한다.

S3 버킷 정책 설정

우리는 방금 생성한 S3 버킷에 대해 크게 네 가지 Sid를 갖도록 정책을 생성할 것이다.

GitHub Actions OIDC를 통해 S3 버킷에 객체를 업로드할 수 있게 함. `Condition` 문을 추가하여 역할을 맡으려는 보안 주체에 대한 추가 요구 사항을 설정할 것.
GitHub Actions OIDC를 통해 업로드 중 객체의 액세스 제어 목록 (ACL)을 변경할 수 있으며, S3 버킷에서 객체를 조회할 수 있게 함.
CodeDeploy가 S3 버킷에서 객체를 조회할 수 있고, 버킷 리스트를 확인할 수 있게 함
EC2 인스턴스가 S3 버킷에서 객체를 조회할 수 있고, 버킷 리스트를 확인할 수 있게 함

따라서 `GitHub Actions ODIC 공급자의 ARN`, `CodeDeploy ARN`, `EC2 인스턴스 ARN`, `S3 버킷 ARN`가 모두 필요하다. 미리 찾아놓자.

범용 버킷 탭에서 생성한 S3 버킷을 클릭하고 권한 탭으로 이동한다. 아래로 이동하면 나오는 버킷 정책에서 편집을 클릭한다.

이동 후 나오는 창에서 정책 생성기를 클릭한다.

Sid 마다 항목별로 입력하고 Add Statement를 클릭하면 된다.

Sid 1.

Step 1: Select policy type: S3 Bucket Policy
Step 2: Add statement(s)
- Effect: Allow
- Principal: IAM > OIDC 공급자 > 등록했던 GitHub Actions 공급자 클릭 > ARN 복사 및 붙여 넣기
- Actions: PutObject
- Amazon Resource Name (ARN): "{생성한 S3 버킷 ARN}"," {생성한 S3 버킷 ARN}/*"
- Add conditions. 아래처럼 입력 후 Add Condition 클릭.
  - Condition: StirngEquals
  - Key: s3:x-amz-server-side-encryption
  - Value: AES256

Sid 2.

Step 1: Select policy type: S3 Bucket Policy
Step 2: Add statement(s)
- Effect: Allow
- Principal: IAM > OIDC 공급자 > 등록했던 GitHub Actions 공급자 클릭 > ARN 복사 및 붙여 넣기
- Actions: PutObjectAcl, GetObject
- Amazon Resource Name (ARN): "{생성한 S3 버킷 ARN}"," {생성한 S3 버킷 ARN}/*"

Sid 3.

Step 1: Select policy type: S3 Bucket Policy
Step 2: Add statement(s)
- Effect: Allow
- Principal: 생성한 CodeDeploy ARN 입력
- Actions: GetObject, ListBucket
- Amazon Resource Name (ARN): "{생성한 S3 버킷 ARN}"," {생성한 S3 버킷 ARN}/*"

Sid 4.

Step 1: Select policy type: S3 Bucket Policy
Step 2: Add statement(s)
- Effect: Allow
- Principal: 생성한 EC2 인스턴스 ARN 입력
- Actions: GetObject, ListBucket
- Amazon Resource Name (ARN): "{생성한 S3 버킷 ARN}"," {생성한 S3 버킷 ARN}/*"

모두 입력했다면 아래에 Generate Policy를 클릭하고, 나오는 팝업에서 Copy Policy를 클릭한다. 다시 버킷 정책 편집창으로 돌아가서 복사한 정책을 JSON 입력란에 붙여 넣기 한다. 완료하면 아래와 같은 JSON 형식의 정책을 확인할 수 있다.

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "{자유롭게_입력_중복안됨}",
			"Effect": "Allow",
			"Principal": {
				"AWS": {GitHub_Actions_OIDC_ARN}
			},
			"Action": "s3:PutObject",
			"Resource": [
				"arn:aws:s3:::{S3_BUCKET_NAME}",
				"arn:aws:s3:::{S3_BUCKET_NAME}/*"
			],
			"Condition": {
				"StringEquals": {
					"s3:x-amz-server-side-encryption": "AES256"
				}
			}
		},
		{
			"Sid": "{자유롭게_입력_중복안됨}",
			"Effect": "Allow",
			"Principal": {
				"AWS": {GitHub_Actions_OIDC_ARN}
			},
			"Action": [
				"s3:PutObjectAcl",
				"s3:GetObject"
			],
			"Resource": [
				"arn:aws:s3:::{S3_BUCKET_NAME}",
				"arn:aws:s3:::{S3_BUCKET_NAME}/*"
			]
		},
		{
			"Sid": "{자유롭게_입력_중복안됨}",
			"Effect": "Allow",
			"Principal": {
				"AWS": {CodeDeploy_ARN}
			},
			"Action": [
				"s3:GetObject",
				"s3:ListBucket"
			],
			"Resource": [
				"arn:aws:s3:::{S3_BUCKET_NAME}",
				"arn:aws:s3:::{S3_BUCKET_NAME}/*"
			]
		},
		{
			"Sid": "{자유롭게_입력_중복안됨}",
			"Effect": "Allow",
			"Principal": {
				"AWS": {EC2_INSTANCE_ARN}
			},
			"Action": [
				"s3:GetObject",
				"s3:ListBucket"
			],
			"Resource": [
				"arn:aws:s3:::{S3_BUCKET_NAME}",
				"arn:aws:s3:::{S3_BUCKET_NAME}/*"
			]
		}
	]
}

모두 확인했다면 변경 사항 저장을 클릭하여 완료한다.

appspec.yml 작성

이제 AWS에서의 작업은 완료되었고, 프로젝트 루트 디렉토리에 `appspec.yml`을 생성한다. 이 파일은 CodeDeploy가 각 배포 단계에서 무엇을 수행해야 하는지 명시한다. 이 글에서는 각 요소가 무엇을 의미하는지는 설명하지 않는다. 사실 보면 어떤 역할을 하는지 자세히는 몰라도 어림잡아 알 수 있다. `AppSpec` 파일의 `hooks`에 대한 자세한 설명은 여기를 참고.

version: 0.0
os: linux

files:
  - source: /
    destination: /home/ubuntu/hello
    overwrite: yes

permissions:
  - object: /
    owner: ubuntu
    group: ubuntu
    mode: 755

hooks:
  BeforeInstall:
    - location: scripts/install_dependencies.sh
      timeout: 300
      runas: root
  ApplicationStart:
    - location: scripts/start_server.sh
      timeout: 300
      runas: ubuntu
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: ubuntu

scripts 작성

이제 루트 디렉토리에 `scripts` 디렉토리를 생성하고 하위에 `install_dependencies.sh`, `start_server.sh`, `stop_server.sh`를 생성한다.

install_dependencies.sh

이 파일은 배포 파일(bundle)이 설치되기 전 실행되며, 애플리케이션 실행에 필요한 라이브러리 등을 설치한다. 이 글에서는 간단한 Gradle, Java 애플리케이션을 실행하는 경우를 다룬다.

각 애플리케이션마다 요구되는 의존성이 다르므로 확인 후 여기에 추가 작성하면 된다. 또한 EC2 인스턴스의 AMI(OS)에 따라 명령어가 다르니 그 부분도 잘 확인하자.

#!/bin/bash

sudo apt update -y

start_server.sh

이 단계는 의존성이나 배포 파일이 설치된 이후에 실행된다.

#!/bin/bash

cd /home/ubuntu/hello
sudo pkill -f java
nohup java -jar build/libs/*.jar > springboot-app.log 2>&1 &

`.jar` 파일이 있는 위치로 이동
실행되고 있는 java 프로그램 종료: 새로운 버전을 실행하기 전에 기존 버전 애플리케이션 종료
`nohup`을 이용한 `.jar` 파일 실행 및 로그 기록
- `nohup`으로 프로그램을 데몬으로 실행
- 프로그램의 표준 출력(1)과 표준 에러(2)를 `springboot-app.log` 파일에 기록
  - `2>&1` : 표준 에러를 표준 출력이 기록되는 같은 파일에 리다이렉트함
- 백그라운드로 실행(&)

stop_server.sh

이 단계는 애플리케이션의 새 버전을 설치하기 전에 실행되므로, 기존 버전을 종료하는 명령어를 작성한다. 지금까지의 순서상으로는 가장 먼저 실행된다.

#!/bin/bash

sudo pkill -f java

deploy.yml 작성

루트 디렉토리에 `.github/workflows/deploy.yml`를 생성한다. 위치만 정확하면 파일 이름은 상관없다.

잠시 확인! 지금까지의 구조!

배포할 작업물이 있는 GitHub 레포지토리로 이동하자. 그리고 Settings > Security > Secrets and variables > Actions로 이동하자. `Repository secrets`에 AWS 계정 ID를 환경변수로 등록하자.

이 코드는 Gradle 프로젝트에 맞춰져 있다. 따라서 아래 코드를 복붙하고 상황에 맞춰 잘 수정하자.

각 단계마다 간단하게 주석을 적어놨으니 꼭! 제대로! 확인!

name: Java CI with Gradle

on:
  push:
    branches: [ "main" ]  # main 브랜치에 push 하면 워크플로우 동작
  pull_request:
    branches: [ "main" ]  # main 브랜치에 PR이 발생하면 워크플로우 동작

env:
  AWS_REGION: {AWS_리소스를_생성한_REGION}
  S3_BUCKET: {S3_BUCKET_이름}
  CODEDEPLOY_APPLICATION: {CodeDeploy_Application_이름}
  CODEDEPLOY_DEPLOYMENT_GROUP: {CodeDeploy_배포그룹_이름}
  
jobs:
  # Job 1. 빌드
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read

    steps:
    # Step 1. 소스코드 가져오기
    - name: Checkout code
      uses: actions/checkout@v4

    # Step 2. Java 환경 설정
    - name: Set up JDK 17
      uses: actions/setup-java@v4
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: Caching gradle dependencies
      uses: actions/cache@v4
      with:
        path: |
          ~/.gradle/caches
          ~/.gradle/wrapper
        key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
        restore-keys: |
          ${{ runner.os }}-gradle-

    # Step 3. Gradle 설정
    - name: Setup Gradle
      uses: gradle/actions/setup-gradle@af1da67850ed9a4cedd57bfd976089dd991e2582 # v4.0.0

    # Step 4. gradlew 실행 권한 얻기
    - name: Grant execute permission for gradlew
      run: chmod +x gradlew

    # Step 5. 애플리케이션 빌드
    - name: Build with Gradle Wrapper
      run: ./gradlew clean bootJar

    # Step 6. 빌드한 JAR 파일 저장
    - name: Upload build artifacts
      uses: actions/upload-artifact@v4
      with:
        name: jar-artifact
        path: build/libs/*.jar

  # Job 2. 배포
  deploy:
    needs: build
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
    # Step 1. 소스 코드 가져오기
    - uses: actions/checkout@v4

    # Step 2. 이전 단계에서 빌드한 JAR 파일 다운로드
    - name: Download build artifacts
      uses: actions/download-artifact@v4
      with:
        name: jar-artifact
        path: build/libs/

    - name: show all files downloaded  # 어디에 저장되었는지 확인용
      run: |
        ls -al build/libs/
        
    # Step 3. OIDC로 AWS credentials 설정
    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::${{secrets.AWS_ACCOUNT_ID}}:role/GitHubActionsRole
        role-session-name: GitHub_to_AWS_via_FederatedOIDC
        aws-region: ${{ env.AWS_REGION }}

    # Step 4. 배포 패키징
    - name: Create deployment package
      run: |
        # Create a temporary directory for deployment package
        mkdir -p deployment-package

        # Create a ZIP file: .jar 파일, AppSpec 파일, scripts 디렉토리 전체
        zip -r deployment-package.zip build/libs/*.jar appspec.yml scripts  

    # Step 5. S3에 패키징 파일 업로드
    - name: Upload to S3
      run: | 
        # Generate a unique filename 
        COMMIT_HASH=$(echo ${{ github.sha }} | cut -c1-7)
        DEPLOYMENT_KEY="deployments/springboot-${COMMIT_HASH}.zip"  # S3 버킷에 deploymenets 객체(디렉토리)가 생기고 그 하위에 springboot-{github_commit_id}.zip 파일이 생긴다.

        # Upload to S3
        aws s3 cp deployment-package.zip s3://${{ env.S3_BUCKET }}/${DEPLOYMENT_KEY}

        # Save the S3 key 
        echo "DEPLOYMENT_KEY=${DEPLOYMENT_KEY}" >> $GITHUB_ENV

    # Step 6. CodeDeploy 트리거
    - name: Deploy with CodeDeploy
      run: | 
        # Create a deployment with CodeDeploy
        DEPLOYMENT_ID=$(aws deploy create-deployment \
          --application-name ${{ env.CODEDEPLOY_APPLICATION }} \
          --deployment-group-name ${{ env.CODEDEPLOY_DEPLOYMENT_GROUP }} \
          --s3-location bucket=${{ env.S3_BUCKET }},key=${{ env.DEPLOYMENT_KEY }},bundleType=zip \
          --deployment-config-name CodeDeployDefault.AllAtOnce \
          --description "Deployment from GitHub Actions - commit ${{ github.sha }}" \
          --query 'deploymentId' \
          --output text)

        echo "Deployment ID: $DEPLOYMENT_ID"
        echo "DEPLOYMENT_ID=${DEPLOYMENT_ID}" >> $GITHUB_ENV

    # Step 7. 배포 완료 대기
    - name: Wait for deployment completion
      run: |
        echo "Waiting for deployment ${{ env.DEPLOYMENT_ID }} to complete..."    

        # Wait for the deployment to finish
        aws deploy wait deployment-successful --deployment-id ${{ env.DEPLOYMENT_ID }}

        # Get deployment status
        STATUS=$(aws deploy get-deployment \
          --deployment-id ${{ env.DEPLOYMENT_ID }} \
          --query 'deploymentInfo.status' \
          --output text)
        
        echo "Deployment completed with status: $STATUS"
        
        if [ "$STATUS" != "Succeeded" ]; then
          echo "Deployment failed!"
          exit 1
        fi

GitHub Actions를 CI로 사용하여 AWS에 배포하는 스크립트는 구글링 하면 많이 나오니, 여기에서는 OIDC 부분만 참고해도 좋다.

확인

여기까지 진행했다면 이번에는 `main` 브랜치에 `push` 해보자! 방금 적은 스크립트에 의해 워크플로우가 트리거 되고, 레포지토리 `Actions` 탭에서 확인할 수 있다. 잘 진행되었다면 아래와 같이 파란 불을 볼 수 있다!

위에서 생성한 S3 버킷도 확인해 보면 `deploymenets/springboot-{github_commit_id}.zip`이 있는 것을 확인할 수 있다.

CodeDeploy 상태도 확인해 보자. CodeDeploy 애플리케이션에서 배포나 배포그룹 탭으로 이동하고, 성공이 있는 것을 확인할 수 있다.

마지막으로 EC2 인스턴스에 배포된 헬스체크 API를 확인해 보자. Postman이든 브라우저든 창에 아래처럼 입력하자.

http://{EC2_퍼블릭_DNS_주소}/{health_check_api_endpoint}

설정한 대로 잘 나왔다면 진짜 끝!

배포 실패의 경우 확인하는 방법

배포가 언제나 성공하면 좋겠지만, 그렇지 않아서...

CodeDeploy > 애플리케이션 > 배포 > 실패한 배포 ID를 클릭하고, 나오는 창에서 하단으로 내리면 배포 수명 주기 이벤트 > `View events` 버튼이 있다(없는 경우도 있는데, 그런 경우에는 `실패한 배포 ID`를 클릭해서 나오는 메시지를 확인하자). 이걸 클릭하면 (그나마) 자세한 실패 원인을 확인할 수 있다.

다음으로

여기까지 잘 성공했다면 이제 CI/CD 구축을 완료한 것이다! 물론 한 대의 인스턴스만을 사용하기 때문에 무중단 배포는 아니지만, 일단 CI/CD 구축 성공을 축하하자

다음 글에서는 현재 조합에서 AWS Elastic Load Balancing(ELB), AWS AutoScaling Group(ASG)를 추가하여 블루/그린 무중단 배포 하는 방법을 다룰 예정이다.

[SQLite Error] SQLITE_BUSY 예외와 WAL 모드

jaamong — Sat, 19 Jul 2025 12:33:18 +0900

SQLite를 로컬 DB로 사용하고 있는 프로젝트에서 잊을만하면 마주치는 에러가 있어서 정리한다. 프로젝트에서는 Hibernate 버전 6을 사용하고 있다.

상황

로그인 API 이후 사용자 정보 수정 API를 시도했을 때 아래와 같은 예외가 발생했다.

org.sqlite.SQLiteException: [SQLITE_BUSY] The database file is locked (database is locked)

`application.yml`에서 `datasource` 설정은 아래와 같다.

  spring.datasource:
    url: jdbc:sqlite:project.db?busy_timeout=5000
    driver-class-name: org.sqlite.JDBC

추가적으로 알아야 할 정보가 있다.

로그인 API는 정상 응답으로 현재 로그인한 사용자의 정보를 반환한다. (transaction: read-only)
사용자 정보 수정 API 또한 로그인 API가 접근하는 엔티티에 접근하며, 이를 수정해야 한다. (transaction: not read-only)

원인

이 문제는 SQLite가 동시 액세스를 처리하는 방식와 Hibernate가 연결을 관리하는 방식에서 비롯된다.

1. SQLite Locking Mechanism

SQLite는 대부분의 엔터프라이즈 데이터베이스가 사용하는 행 수준(row-level)이 아닌, 파일 수준(file-level) lock을 사용한다.
읽기 작업에 대해서, 한 트랜잭션이 시작하면 SQLite는 파일에 대해 `shared lock`을 건다.
- 다른 프로세스가 읽기 작업은 가능하지만, 쓰기 작업은 할 수 없다.
쓰기 작업에 대해서, 한 트랜잭션이 시작하면 SQLite는 파일에 대해 `exclusive lock`을 건다.
- 다른 프로세스는 쓰기 작업을 할 수 없다.
이러한 잠금은 예상보다 길어질 수 있다.

2. Hibernate Connection Management

Hibernate는 데이터베이스 커넥션을 트랜잭션 완료 이후에 바로 해제하지 않는다.
커넥션은 커넥션 풀에 반환되지만, SQLite 파일 lock은 지속될 수 있다.
수정 API가 `exclusive lock`을 획득하려고 할 때, 로그인 API의 read-only 트랜잭션은 여전히 `shared lock`을 유지하고 있을 수 있다.

3. Transaction Isolation

두 API의 트랜잭션이 분리되어 있어도, 시간적으로는 겹칠 수 있다.
SQLite의 기본 `journal mode`인 `DELETE`는 이러한 잠금 문제가 발생하기 쉽다.

읽기 시작 → `shared lock` 획득 → 모든 쓰기 작업 차단
쓰기 대기 → `SQLITE_BUSY` 에러 발생

즉, 수정 API를 통해 쓰기 작업(exclusive lock)을 시도했지만, 여전히 로그인 API의 읽기 작업으로 걸린 `shared lock`이 해제되지 않아서 발생한 문제이다.

해결

찾아본 해결 방법은 다음과 같다.

동시 접근을 위한 설정 추가: `application.yml` 수정
수정 기능에 재시도 메커니즘 추가: Spring `@Retryable` 애노테이션 사용
애플리케이션 수준의 동기성 제어: Java `synchronized` 사용

우선 `application.yml` 수정을 시도해보고 동일 문제가 발생하면 점진적으로 수정 단계를 높여가는 것으로 정했다.

spring:
  datasource:
    url: jdbc:sqlite:project.db?busy_timeout=30000&journal_mode=WAL&synchronous=NORMAL&cache_size=10000&temp_store=MEMORY
    driver-class-name: org.sqlite.JDBC

1. journal_mode=WAL

이 옵션은 `Write-Ahead Logging`을 활성화하여 더 나은 동시성을 허용한다. 메인 데이터베이스 파일을 변경하는 것이 아닌 분리된 WAL 파일에 쓰기 작업을 진행한다. 읽을 때는 메인 데이터베이스와 커밋된 WAL 엔트리를 읽게 된다.

읽기 작업 → 읽기: 메인 DB + WAL 파일 → No blocking
쓰기 작업 → WAL 파일에 쓰기 → 동시 진행 가능

동시에 여러 읽기 작업을 할 수 있고 이때 하나의 쓰기 작업도 가능하다. (하지만 여전히 동시 여러 쓰기 작업은 지원하지 않는다)

2. synchronous=NORMAL (문제 해결 X, 쓰기 성능 향상 목적)

이 옵션은 SQLite가 디스크에 데이터를 동기화하는 빈도를 조절할 수 있다.

`OFF` : 가장 빠르지만, 가장 안전하지 않은 옵션
`NORMAL` : 균형잡힌 상태. 안전성을 유지하면서 `fsync` 호출을 줄인다.
`FULL` : 가장 안전하지만, 가장 느리다.

이제 모든 쓰기 작업마다 `fsync`를 호출하지 않으며, 중요한 순간에만 동기화 된다. 다만 서버가 다운되면 데이터 소실이 일어날 수 있다.

3. cache_size=10000 (문제 해결 X, 읽기 성능 향상 목적)

페이지(Page)는 SQLite에서 데이터를 다루는 기본 단위이다. 이 옵션은 페이지 캐시 사이즈를 설정한다. 기본적으로 2000 pages로 설정되어 있다.

사이즈를 높임으로써 메모리를 더 사용하게 된다. 이는 메모리에 더 많은 데이터를 유지할 수 있고, 자주 접근되는 데이터는 캐시에서 가져올 수 있음을 의미한다. 또한 무거운 읽기 작업에 대해 더 나은 성능을 제공하게 된다.

4. temp_store=MEMORY (문제 해결 X, 성능 향상 목적)

기본 설정은 `FILE`로 임시 작업에 대해 디스크를 사용한다. `MEMORY`로 변경하면 임시 테이블, 인덱스, 정렬 작업에 대해 disk 대신 메모리를 사용하게 된다. 임시 파일은 file lock을 위해 경쟁하지 않게 된다(lock 경쟁 감소).

이는 sorting, join 쿼리와 같은 곳의 성능을 높일 수 있다.

5. busy_timeout=30000

데이터베이스가 잠겼을 때(lock) 포기하기 전에 얼마나 대기할지 설정

.db-wal, .db-shm

위 설정을 적용하고 나서 서버를 가동하고 나니 db 파일 외에 다른 파일이 추가로 생성되었다.

`.db-wal` 파일은 커밋되지 않은 쓰기 작업을 담고 있다. 새로운 데이터는 처음에 여기에 쓰이고 후에 메인 데이터베이스로 이동된다(Write-Ahead Log). 처음 쓰기 작업이 발생할 때 생성되며, 체크포인트될 때까지 유지된다.

`.db-shm` 파일은 더욱 빠른 접근을 위해 WAL 파일을 인덱싱하는 목적을 갖고 있다. WAL 파일과 함께 생성되고 WAL이 체크포인트되면 삭제된다.

이 두 파일은 런타임 시 발생하는 것이므로 굳이 버전 관리 저장소에 올리거나 배포할 때 포함시키지 않는다.

Hexagonal Architecture / Ports & Adapters Pattern

jaamong — Sat, 12 Jul 2025 17:39:55 +0900

Notice

이 글은 개인적으로 읽기 편하라고 개인 노션에 막 정리한 글을 공유한 것입니다. 스스로가 정리한 것을 까먹지 않기 위함...

배경

Hexagonal Architecture인지 포트 어댑터 패턴인지... 여러 개념들이 등장해서 어딘가 적어두면서 생각하지 않으면 이해하기가 너무 어렵다.

그래서 라인에서 작성한 글을 메인으로 잡고 잘 모르는 개념을 검색하며 노션에 막! 정리했다.

https://www.notion.so/Hexagonal-Port-Adapter-22ee4ff26d86807497cbe5ddd763765d?source=copy_link

후기

살짝 프로젝트 적용해 보면서 느낀 점은 우선... 다 좋은데 코드 작성량이 정말 많이 많아진다. 필요한 무언가가 있으면 이걸 위해서 작성해야 하는 코드(파일)들이 +1이 아니라 +n이 되기 쉽다. 패키지도 많이 만들어진다. 그리고 개념을 정확히 알아두지 않으면 클래스 생성할 때마다 어디에 둬야 하는지 혼란스럽고, 이게 맞나? 싶어진다.

영속 계층과 애플리케이션 계층이 분리되어야 하다보니 이 계층 간 데이터 이동이 JPA 엔티티가 아니라 POJO를 통해 이루어지는데, 이때 레이어드 아키텍처랑 Spring Data JPA에 매우 익숙해져 있으면 처음에 트랜잭션 관련으로 불편을 겪을 수도 있다.

장점은 보통 `@Service`를 붙이는 클래스들이 깔끔해지고 설계 방향성이 뚜렷하다 보니 DTO를 이동시킬 때 일관되게 만들 수 있다. 연관된 친구들끼리 두니 의도 파악에도 좋다. 테스트도 가벼워진다. 이 부분에서 크나큰 좋음을 느꼈다. (그런데 이제 수많은 코드 생성을 곁들인...)

참고

여기에는 다양한 참고 링크가 있습니다만, 노션에 첨부해뒀습니다.

[Spring Security] @CurrentUser

jaamong — Sat, 12 Jul 2025 12:09:37 +0900

스프링 시큐리티는 `@AuthenticationPrincipal` 애노테이션을 제공한다. 이는 `Authenticaiton.getPrincipal()`를 메서드 인자로 가져오는 데 사용되며, 보통은 `UserDetails` 타입이나 해당 타입의 커스텀 구현체로 가져오게 된다.

`Authentication.getPrincipal()`에는 username, password(AuthenticationManager 구현에 따라 없을 수 있음), role과 같은 사용자 정보가 담겨있다.

간단하게 해당 애노테이션을 그대로 사용해도 되지만, 더 편리하게 사용할 수 있다. 이는 공식문서에서도 안내하고 있다.

실제로 구현해 보자. 여기서는 커스텀 애노테이션 이름을 `@CurrentUser`로 설정했다.

import org.springframework.security.core.annotation.AuthenticationPrincipal;

import java.lang.annotation.*;

/**
 * 익명 사용자인 경우에는 null로, 익명 사용자가 아닌 경우에는 실제 Users 객체로
 */
@Target({ElementType.PARAMETER, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@AuthenticationPrincipal(expression = "#this == 'anonymousUser' ? null : user")
public @interface CurrentUser {
}

`@AuthenticationPrincipal.expression`에 SpEL 표현식을 사용하여 원하는 값을 가져오도록 설정할 수 있다. 위 표현식은 다음을 의미한다.

현재 객체(`#this`)가 익명 사용자(`anonymousUser`, 인증되지 않음)라면 `null`을 반환
아니라면, `Authentication.getPrincipal()`을 통해 사용자를 나타내는 객체(`UserDetails` 또는 다른 구현체)를 반환

구현을 완료하면 다음과 같이 사용자 객체를 간편하게 애노테이션으로 가져올 수 있다.

...
public class UserController {
	
    ...

    @GetMapping("/info")
    public ResponseEntity<ResponseBody<UserInfo>> getInfo(@CurrentUser Users user) {
        UserInfo userInfo = userInfoService.get(user);
        return ResponseUtil.from(HttpStatus.OK.value(), userInfo);
    }
    ...
}

참고로 위에서 사용한 `Users` 객체는 직접 정의한 도메인 객체이다. `UserDetails` 구현체는 아니지만, `UserDetailsService. loadUserByUsername`에서 `UserDetails` 구현체를 생성하여 반환할 때 `Users` 객체를 인자로 넣어주고 있어서 가능하다.

public class UserDetailsServiceImpl implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String email) {
        Users user = userRepository.findByEmail(email)
                .orElseThrow(() -> new UsernameNotFoundException(NOT_FOUND_USER.getMessage()));
        return new CustomUserDetails(user); // 커스텀 UserDetails 클래스 생성자에 직접 구현한 Users 객체를 인자로 넘김
    }

}

[Spring Security] 세션 기반 로그인 구현하기

jaamong — Sat, 5 Jul 2025 12:49:34 +0900

Spring Security 6.5.0 기준 작성

로그인을 구현할 때 보통 JWT를 많이 사용하는데, 이번에는 세션 기반으로 구현했다.

일단... JWT를 사용하여 로그인과 로그아웃을 구현하면 신경 쓸 것이 꽤 많다. 특히 로그아웃이 복잡한 것 같다.

사용자 인증을 위한 액세스 토큰(Access Token) 및 액세스 토큰 재발급을 위한 리프레시 토큰(Refresh Token) 생성
요청 시 사용된 토큰이 유효한지 검증(만료, 변조 여부 등)
로그아웃을 해도 액세스 토큰의 만료기간이 남아있다면 재사용 가능 → 이를 막기 위해 로그아웃 시 해당 액세스 토큰을 블랙리스트(저장소)에 저장
- 블랙리스트 저장소에 대한 액세스 속도를 높이기 위해 보통 Redis와 같은 인메모리 DB를 사용한다.
- 한 번은 블랙리스트 사용말고 다른 방법이 없나 찾아봤다.
  - 리프레시 토큰은 DB에 저장해야 하니 로그아웃 요청이 들어오면 리프레시 토큰을 DB에서 제거하는 방법을 사용한 적도 있다. 이러면 다시 인증을 수행할 수밖에 없다.

이외에도 고민할 것은 더 많을 것이다. 그래서 지금은 (배포 금지) MVP 단계이기도 하고, 주어진 개발 시간이 매우 짧기 때문에 세션 기반 로그인으로 선택했다.

Note 세션 기반 로그인 구현의 경우, 서버는 로그인이 성공하면 쿠키에 `JSESSIONID` 값을 담아 응답을 반환한다. 클라이언트는 서버로 인증이 필요한 요청을 보낼 때 이 값을 쿠키에 담아 보내야 한다.

세션 인증 필터 구현하기

요청이 들어오면 무엇을 해야 할까?

JWT를 사용하는 경우, 로그인 시 로그인 요청 정보가 유효한 회원 정보면 JWT를 생성하고 이를 클라이언트에게 반환하는 것이 기본 흐름이다.

필터 수준으로 생각해보자. 일단 매 요청마다 JWT 검증 필터를 거치게 하고, 로그인과 같이 인증이 필요 없는 요청인 경우에는 JWT 검증을 하지 않는다. 이때 (1)요청 경로가 로그인 URI이고 (2)요청 바디에 담긴 정보가 DB에 저장된 정보와 일치하면 (3)JWT를 생성하고 (4)이 토큰을 `SecurityContext`에 저장하여 인증이 유지되도록 한다.

이 역할을 수행하는 필터는 보통 `OncePerRequestFilter`를 상속하여 구현되며, `UsernamePasswordAuthenticationFilter` 이전에 실행된다.

세션 기반으로 구현할 때도 로그인을 처리하고 새로운 세션을 생성하여 인증을 유지하기 위한 필터가 필요하다. 마찬가지로 매 요청마다 수행하기 위해 `OncePerRequestFilter`를 상속하여 커스텀 필터를 구현했다. 이 필터에서는 다음의 것들이 수행된다.

인증이 필요하지 않은 요청인지 확인
- 다음 필터 호출
로그인 요청인지 확인
- 사용자 정보가 유효한지 검증
- 유효하다면 새로운 세션 생성 및 저장
위 두 조건에 모두 해당하지 않는다면 HTTP 세션에서 현재 요청의 `SecurityContext`로 사용자 인증 상태를 복원

SessionBasedAuthenticationFilter

위에서 언급한 일을 수행하는 필터를 구현해 보자.

아래 코드는 `OncePerRequestFilter`를 상속하고, 이 필터의 추상 메서드인 `doFilterInternal` 로직을 구현한다.

@Slf4j
@Component
@RequiredArgsConstructor
public class SessionBasedAuthenticationFilter extends OncePerRequestFilter {

    private final Set<String> NOT_AUTH_URI = Set.of(
            "/health",
            "/user/join",
            ...
    );

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {

        if (NOT_AUTH_URI.contains(request.getRequestURI())) { // 인증이 필요없는 요청
            filterChain.doFilter(request, response);
            return;
        }

        String loginUrl = "/user/login";
        if (loginUrl.equals(request.getRequestURI())) { // 로그인 요청
            handleLogin(request, response);
            filterChain.doFilter(request, response);
            return;
        }

        // 인증이 요구되는 요청
        loadAuthenticationFromSession(request); 
        filterChain.doFilter(request, response);
    }
    ...
}

첫 번째 `if`문에서는 인증이 필요 없는 요청인지 확인한다. 맞다면,
- 세션으로부터 인증 객체를 가져와서 무언가를 수행할 필요가 없는 요청이기 때문에 다음 필터를 호출한다.
- 호출 이후 돌아오면 필터를 종료시킨다.
두 번째 `if`문에서는 로그인 요청인지 확인한다. 맞다면,
- 로그인 관련 로직을 수행하는 `handleLogin` 메서드를 호출한다.
- 수행 후 다음 필터를 호출하고, 호출 이후 돌아오면 필터를 종료시킨다.
모든 조건에 부합하지 않는다면, 조건을 따져 세션으로부터 사용자 인증 상태를 복원한다.

이번에는 로그인 요청이 맞다면 로그인 자격 증명을 수행하는 `handleLogin` 메서드를 구현한다.

@Slf4j
@Component
@RequiredArgsConstructor
public class SessionBasedAuthenticationFilter extends OncePerRequestFilter {

    private final Set<String> NOT_AUTH_ENDPOINT = Set.of(...);

    private final AuthenticationManager authenticationManager;
    private final SecurityContextRepository securityContextRepository = new HttpSessionSecurityContextRepository();
    private final ObjectMapper objectMapper = new ObjectMapper();
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        ...
    }
    
    private void handleLogin(HttpServletRequest request, HttpServletResponse response) {
        try {
            UserLogin loginRequest = objectMapper.readValue(request.getInputStream(), UserLogin.class);
            // 인증 처리
            UsernamePasswordAuthenticationToken authenticationToken =
                    new UsernamePasswordAuthenticationToken(loginRequest.getEmail(), loginRequest.getPassword());
            Authentication authentication = authenticationManager.authenticate(authenticationToken);

            SecurityContext context = SecurityContextHolder.createEmptyContext();
            context.setAuthentication(authentication);
            SecurityContextHolder.setContext(context);

            // 세션 저장
            securityContextRepository.saveContext(context, request, response);

            // 타임아웃 설정 - 1시간
            HttpSession session = request.getSession();
            session.setMaxInactiveInterval(3600);
        } catch (UsernameNotFoundException e) {
            log.error(...);
            request.setAttribute("exception", e.getMessage());
        } catch (BadCredentialsException e) {
            log.error(...);
            request.setAttribute("exception", e.getMessage());
        } catch (IOException e) {
            log.error(...);
            request.setAttribute("exception", e.getMessage());
        }
    }

`ObjectMapper`를 이용하여 요청 바디를 추출한다.
요청 바디로부터 사용자 이메일 또는 닉네임 및 비밀번호를 추출하여 `UsernamePasswordAuthenticationToken` 타입의 인증 토큰을 생성한다.
생성한 토큰을 `AuthenticationManager.authenticate()`로 보내 유효한지 검증한다.
- 실제로 이를 수행하는 건 `AuthenticationProvider`를 구현한 커스텀 `UsernamePasswordAuthenticationProvider` 클래스의 `authenticate` 메서드이다.
- `authenticate()`에서는 `UserDetailsService.loadUserByUsername` 구현체를 사용하여 DB에 저장된 정보와 요청 정보가 일치하는지 검증한다. 유효하면 새로운 `Authentication` 객체를 생성하여 반환하고, 유효하지 않은 경우 `UsernameNotFoundException` 또는 `BadCredentialsException` 예외를 던진다.
  - 이렇게 발생한 예외들은 `AuthenticationEntryPoint`를 통해 처리된다.
새로운 `SecurityContext`를 생성하고, 여기에 위에서 생성한 인증 객체를 설정한다.
`SecurityContextHolder`에 위 `SecurityContext`를 설정한다.
`HttpSessionSecurityContextRepository`에도 컨텍스트를 저장하여 요청 간 컨텍스트을 유지한다.
- `HttpSessionSecurityContextRepository`는 인증된 사용자의 `SecurityContext`를 HTTP 세션에 저장하고 관리하는 역할을 수행한다. 즉, 사용자가 로그인하면 해당 사용자의 인증 정보(Ex. 사용자 ID, 권한 등)를 세션에 저장하여, 이후 요청에서도 해당 정보를 재사용할 수 있도록 한다.
마지막으로, 요청 객체에서 세션을 추출하여 만료 시간을 설정한다.

이제 세션으로부터 기존에 저장된 인증을 가져오는 `loadAuthenticationFromSession`을 구현한다.

그전에 알아둘 것이 있다!

HTTP는 상태를 유지하지 않는다.(stateless) → 각 요청은 새로이 시작하며 독립적이다.
사용자가 1분 전에 로그인을 해서 `authentication`이 세션이 저장됐더라도, 새로 들어온 요청은 `authentication`이 없다.
- `authentication`은 세션에 존재하지만 현재 요청의 `SecurityContext`에는 없다.
이 메서드는 세션으로부터 현재 요청의 `SecurityContext`에 `authentication`을 가져오는 역할을 수행한다. → 이제 현재 요청도 인증된 것으로 나타난다.
만일 세션이 만료되었거나 로그인한 적이 없다면
- 세션에서 `authentication`을 찾을 수 없음
- 현재 요청은 인증되지 않은 상태로 유지됨
- Spring Security이 인증 상태를 확인하지만, `authentication`이 없음 → `AuthenticationEntryPoint`가 401 에러를 반환

이 메서드는 유효한 인증 세션이 있는 클라이언트의 요청을 다루지만, 현재 요청 스레드에는 아직 인증이 로드되지 않은 상태이다. 즉, 클라이언트가 인증된 상태인지 검증하는 것이 아니라 `authentication`을 복원하는 로직이다.

@Slf4j
@Component
@RequiredArgsConstructor
public class SessionBasedAuthenticationFilter extends OncePerRequestFilter {

    private final Set<String> NOT_AUTH_ENDPOINT = Set.of(...);

    private final AuthenticationManager authenticationManager;
    private final SecurityContextRepository securityContextRepository = new HttpSessionSecurityContextRepository();
    private final ObjectMapper objectMapper = new ObjectMapper();
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        ...
    }
    
    private void handleLogin(HttpServletRequest request, HttpServletResponse response) {
        ...
    }
    
    private void loadAuthenticationFromSession(HttpServletRequest request) {
       
        // 세션에 이미 authentication 객체가 존재하는지 확인 (중복 저장 방지)
        if (SecurityContextHolder.getContext().getAuthentication() != null) {
            return;
        }

        SecurityContext context = securityContextRepository.loadDeferredContext(request).get();

        if (context != null &&
                context.getAuthentication() != null &&
                context.getAuthentication().isAuthenticated()) {
            SecurityContextHolder.setContext(context);
        }
    }
}

`authentication`이 이미 존재하는지 확인한다.
- 다른 필터가 이미 `authentication`을 설정했는지 확인하여 중복 처리를 방지
- SecurityContext에서 기존 `authentication`을 덮어쓰지 않기 위함
HTTP 세션에서 이전에 저장된 `SecurityContext`를 가져온다.
- 이때 deprecate 된 `loadContext` 메서드는 사용할 수 없으므로 `loadDeferredContext` 메서드를 사용해야 한다.
- 이 컨텍스트는 사용자의 인증 정보를 담고 있다. (로그인 처리 시 저장한 것을 떠올리기!)
- `HttpSessionSecurityContextRepository`를 사용하여 세션 저장소에 접근한다.
불러온 컨텍스트가 유효한지, 인증된 사용자 정보를 담고 있는지 확인한다. 조건에 부합하면
- 현재 요청에 대해서 `SecuritnContext`를 설정한다.
- 이렇게 함으로써 컨트롤러나 다른 곳에서 사용자 인증을 사용할 수 있게 된다.

SecurityConfig

설정 클래스에서는 위에서 구현한 필터가 `UsernamePasswordAuthenticationFilter` 전에 실행되도록 필터 체인에 등록하면 된다.

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final String[] PERMIT_ALL_URL = {...};
    private final SessionBasedAuthenticationFilter sessionBasedAuthenticationFilter;
    private final AuthenticationEntryPoint authenticationEntryPoint;
    private final AccessDeniedHandler accessDeniedHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .formLogin(AbstractHttpConfigurer::disable)
                .headers(headers -> headers.frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin))
                .csrf(AbstractHttpConfigurer::disable)
                .cors(cors -> cors.configurationSource(CorsConfig.corsConfigurationSource()))
                .authorizeHttpRequests(
                        auth -> auth
                                .requestMatchers(CorsUtils::isPreFlightRequest).permitAll()
                                .requestMatchers(PERMIT_ALL_URL).permitAll()
                                .anyRequest().authenticated()
                )
                .addFilterBefore(  // here
                        sessionBasedAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
                .exceptionHandling(e -> e
                        .authenticationEntryPoint(authenticationEntryPoint)
                        .accessDeniedHandler(accessDeniedHandler)
                );
        return http.build();
    }

참고로 필터 체인 빈 외에 시큐리티와 관련하여 필요한 빈들은 다른 설정 클래스에 두었다. 여러 컴포넌트와 참조되는 상태라 같이 두면 순환 참조가 발생할 확률이 높다. (CORS는 아예 전용 설정 클래스를 만들어 두는 게 편해서 따로 빼두었다.)

@Configuration
public class SecurityDependencyConfig {

    @Bean
    public AuthenticationManager authenticationManager(UserDetailsService userDetailsService, PasswordEncoder passwordEncoder) {
        DaoAuthenticationProvider authenticationProvider = new DaoAuthenticationProvider(userDetailsService);
        authenticationProvider.setPasswordEncoder(passwordEncoder);
        return new ProviderManager(authenticationProvider);
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

위 설정 클래스에서 `AuthenticationManager`는 `DaoAuthenticationProvider`로 구현할까 했는데, 기본 생성자는 deprecate 되었다. 이제는 `UserDetailsService`를 파라미터로 받는 생성자를 사용해야 하며 `PasswordEncoder`는 setter를 사용하는 것으로 바뀌었다. (이 내용을 좀 뒤늦게 찾아서 처음에는 일단 `UsernamePasswordAuthenticationProvider`를 대신 사용했다)

이제 세션 기반 로그인 구현이 완료되었다!

[SQLite] 타입 친화성(Type Affinity)

jaamong — Sat, 21 Jun 2025 17:00:18 +0900

평소에 SQLite는 테스트용으로만 사용하고 실제로는 잘 사용하지 않는데, 설치가 불필요한 로컬 RDB가 요구되는 프로젝트를 진행하게 되어 SQLite를 사용하기로 했다.

타입 종류

SQLite는 대표적인 RDBMS인 MySQL이나 PostgreSQL 등과 달리 데이터 타입이 매우 적다. 다음은 SQLite에서 제공하는 storage class이다.

TEXT : 데이터베이스 인코딩(UTF-8, UTF-16BE or UTF-16LE)을 사용하여 저장된 텍스트 문자열
INTEGER : 값 크기에 따라 0, 1, 2, 3, 4, 6, 8 바이트로 저장되는 정수(signed integer)
REAL : 8 바이트 IEEE 부동 소수점 숫자로 저장되는 부동 소수점 값
BLOB : 입력 그대로 저장되는 데이터
NULL : NULL 값

문자열을 저장할 때 문자열을 지원하는 다양한 타입을 고민할 필요 없이 `TEXT`에 저장하면 된다. `BOOLEAN` 타입은 `INTEGER` 타입에 0(FALSE) 또는 1(TRUE) 값으로 저장하면 된다.

Note JPA를 사용한다면 `Boolean` 타입 필드에 `@Column(columnDefinition="INTEGER")`을 적용해서 타입을 명시하자.

날짜 및 시간

위에서 보이는 것처럼 날짜(date)나 시간(time) 관련 타입은 따로 제공하지 않기 때문에 `TEXT`, `REAL` 또는 `INTEGER`로 저장해야 한다.

TEXT : "YYYY-MM-DD HH:MM:SS.SSS"
REAL : 율리우스 일수로, 기원전 4714년 11월 24일 그리니치 정오 이후의 일수(예상 그레고리력 기준)
INTEGER : 유닉스 시간으로, 1970년 1월 1일 00:00:00 UTC 이후의 초 수

이렇게 저장된 데이터는 내장된 날짜/시간 함수를 사용해서 형식을 자유롭게 변환할 수 있다.

개인적으로 `LocalDateTime` 형식과 유사한 `TEXT` 타입을 선호한다. 위 포맷으로 저장하고 변환하는 유틸을 만들어두면 편리하다. 다만 포맷터가 있다 하더라도 `createdAt`, `modifiedAt` 등과 같이 날짜 시간 타입을 다룰 때 손이 더 가는 건 어쩔 수 없다.

다음은 이번에 프로젝트를 진행하면서 작성했던 코드로, 공통으로 사용하는 `createdAt`, `modifiedAt` 필드를 담고 있는 클래스이다.

@Getter
@MappedSuperclass 
public abstract class BaseEntity {

    @Column(name = "created_at", updatable = false)
    protected String createdAt; // 이 클래스를 상속받는 다른 클래스에서 접근하기 위해서 protected로 선언

    @Column(name = "modified_at")
    private String modifiedAt;

    @PrePersist
    protected void onCreate() {
        createdAt = CommonUtils.localDateTimeToString(LocalDateTime.now());
        modifiedAt = CommonUtils.localDateTimeToString(LocalDateTime.now());
    }

    @PreUpdate
    protected void onUpdate() {
        modifiedAt = CommonUtils.localDateTimeToString(LocalDateTime.now());
    }
}

처음에는 `LocalDateTime` 필드로 선언하고 `@Column` 애노테이션을 사용해서 `TEXT` 타입을 명시해줬는데 오히려 일이 복잡해져서 처음부터 `String` 타입으로 선언하고 따로 컬럼 삽입이나 변경 시 동작하는 메서드를 만들었다.

또한 `@PrePersist`, `@PreUpdate`를 사용하기 때문에 JPA auditing 기능은 필요하지 않다.

Note SQLite에서 `DEFAULT CURRENT_TIMESTAMP`는 지원하지만, `ON UPDATE CURRENT_TIMESTAMP`는 지원하지 않는다.

타입 친화성

SQLite는 다른 데이터베이스와의 호환성을 위해 타입 친화성을 지원한다. 이는 다음을 의미한다.

컬럼을 SQLite에는 없는 `FLOAT`나 `TIMESTAMP` 타입 등으로 선언할 수 있다.
이렇게 선언된 컬럼을 SQLite는 내부적으로 위에서 소개한 5가지 storage class 중 하나로 매핑한다.
따라서 네이티브 하지 않은 타입으로 선언된 컬럼들도 SQLite에서 기술적으로 유효하다.

따라서 `Double` 타입 필드에 `@Column(columnDefinition="REAL")`을 사용해서 타입을 명시하지 않아도 실행했을 때 오류가 발생하지 않는다. 실행 시 Hibernate가 만드는 쿼리를 보면 해당 컬럼이 `REAL` 타입으로 선언되지 않고, `Double` 타입으로 들어가는 것을 확인할 수 있다.

Note Hibernate community dialect 의존성을 추가해도 SQLite에 있는 타입으로 변환되지 않는다.

이러한 타입 친화성 덕분에 오류가 나지는 않지만 그래도 컬럼을 명시하는 방향을 지향한다.

참고

https://www.sqlite.org/datatype3.html

Render로 FastAPI 배포한 후기

jaamong — Sat, 8 Mar 2025 16:03:21 +0900

근래 FastAPI + PostgreSQL 조합으로 백엔드 개발을 진행하고 있다. 프론트엔드에서 API를 가져다 쓰려면 배포를 해야 하므로 처음에는 AWS의 EC2나 Lambda, Elastic Beanstalk을 고려했다. (고려하면서 좀 찾아봤는데 셋 다 목적이 달라서 어쩌다 보니 공부하게 된건 덤)

백엔드 개발 규모가 그리 크지 않아서 AWS를 사용하는 건 부담스럽게 느껴졌다. 그렇게 다른 플랫폼을 찾다 보니 Render를 선택했다.

사실 전에 Java(SpringBoot)도 가능하다는 말을 어디선가 봐서 도전했다가 안 좋은 감정만 남았던 기억이 있는데, 사용 후기가 꽤 있는 Python은 뭔가 다를지도 몰라! 하는 기대감으로 도전했다.

Render는 여타 다른 클라우드 플랫폼이 그렇듯 여러 플랜과 인스턴스 타입을 지원한다. 그중에서 내가 사용 중인 건 Hobby 플랜의 무료(Free) 인스턴스이다. 해당 스펙이 규모가 작은 개발 단계에서 사용하기 적합했다. 선택한 다른 이유로는 빌트인 PostgreSQL을 지원하는 것과 GitHub로부터 자동 배포를 해준다는 점이었다. 월마다 무료 사용량으로 750시간이 주어지는 것도 충분했다. (자세한 사항은 Render에서 확인)

Monthly usage limits - Free instance hours

무료 인스턴스의 단점이라면 요청을 처리하는데 50초 이상 지연되거나, 15분 이상 요청이 들어오지 않으면 자동으로 서버가 내려간다는 정도다. 실제로 서비스할 때는 Starter 인스턴스(7$ / month)를 써보려고 한다.

Instance Types

더불어 같이 제공해 주는 빌트인 PostgreSQL도 좋았다. 배포한 FastAPI 애플리케이션과의 연동이 매우 간단하고, pgAdmin을 통해서 외부에서도 접근할 수 있다. 설정만 잘하면 된다.

종합 후기

파이썬으로 백엔드 개발을 하고 있고 배포를 해야 한다면 Render도 고려할만한 것 같다.

(뭔가 광고, 홍보글처럼 작성한 것 같은데 절대 아니라는 점...)

FastAPI 개발 환경 설정과 애플리케이션 시작하기

jaamong — Sat, 8 Feb 2025 09:27:50 +0900

보통 백엔드 개발 시 주로 스프링 부트를 사용하는데, 파이썬을 사용하는 AI 엔지니어와 협업할 때 호환성이 좋지 않았다. 그래서 AI 엔지니어와 협업할 때만 사용할, 스프링 부트를 대체할 파이썬 기반 백엔드 프레임워크 사용을 계속 고민해 왔다.

인증이나 주된 기능은 스프링 부트로 처리하되 AI 프로그램에서 넘어오는 데이터를 처리하고 API로 전달하는 용도로 쓰고자 했다. 따라서 비교적 무거운 Django를 제외하고 Flask와 FastAPI 중에서 고민했다.

이전에 사용해 본 Flask는 Java로 백엔드 개발하는 것과 비슷한 부분이 있어서 끌렸는데, FastAPI는 Flask와 동일하게 API나 마이크로서비스 개발 등에 적합하며 API 문서 자동화를 지원한다고 한다! API 문서 자동화 지원은 사용할 이유로 충분했다.

환경 설정

⚠️파이썬이 먼저 설치되어 있어야 한다. 없다면 여기로 가서 최신 버전을 설치하고 시스템 환경 변수에 추가하자.

파이썬 설치가 완료되었다면 이제 FastAPI와 Uvicorn을 설치해야 한다.

Uvicorn은 FastAPI를 실행하는 가벼운 ASGI 서버이다.

FastAPI와 Uvicorn을 설치하기 위해 아래 명령어를 터미널에 입력하자.

pip install fastapi uvicorn

설치가 완료되면 FastAPI 애플리케이션을 빌드할 수 있다. → 환경 설정 끝!

간단한 애플리케이션 만들기

우선 FastAPI를 `import` 해야 한다. 이는 FastAPI 인스턴스 생성에 필요하다.

from fastapi import FastAPI  # fastapi 모듈에서 FastAPI 클래스 import

app = FastAPI()  # FastAPI 클래스의 인스턴스 생성

`app`은 서버로 들어오는 모든 요청을 처리하는 메인 애플리케이션이 된다.

이제 Path operation(API)을 정의한다.

"/" 경로로 요청이 들어온다.
처리하는 함수명은 `read_root`이다.
`"hello"`와 `"world"`를 담은 딕셔너리 데이터를 반환하다.

from fastapi import FastAPI 

app = FastAPI()  


@app.get("/")
def read_root():
    return {"hello", "world"}

이제 Uvicorn을 사용하여 서버를 실행하자.

uvicorn main:app --reload

`uvicorn main:app` : 메인 앱이 Uvicorn에게 `main.py`안에 존재하는 `app` 인스턴스를 찾으라고 한다.
`--reload` : 코드에 변경사항에 생기면 서버가 자동으로 재시작된다.

터미널에서 명령어 입력

서버 실행 후 localhost:8080/ 접근 결과

문서 자동화

위에서 언급했던 것과 같이 FastAPI는 문서 자동화 기능을 지원한다.

`/docs`으로 접근하면 Swagger 형태로, `/redoc`으로 접근하면 Redoc 형태로 API 문서를 제공한다.

/docs로 접근 시 Swagger 형태

/redoc으로 접근 시 Redoc 형태

[AWS RDS] MySQL 파라미터 그룹 생성과 설정 - timezone, encoding

jaamong — Fri, 31 Jan 2025 09:14:58 +0900

RDS MySQL를 사용하는 프로젝트에서 시간대가 맞지 않음을 알게 되었다. 타임존 설정을 까먹은 것...!

해당 DB 인스턴스의 설정을 바꾸는 일이므로 DB 파라미터 그룹을 새로 생성하여 수정하기로 했다.

DB 파라미터 그룹

DB 파라미터 그룹은 하나 이상의 DB 인스턴스에 적용되는 구성 값의 모음이다. DB 파라미터 그룹을 지정하지 않고 DB 인스턴스를 만드는 경우 DB 인스턴스에서는 기본 DB 파라미터 그룹을 사용한다.

기본 DB 파라미터 그룹 설정은 수정할 수 없으므로 새 파라미터 그룹을 생성해야 한다. 그리고 원하는 파라미터 설정을 변경하고, DB 인스턴스나 DB 클러스터를 수정하여 새로 생성한 파라미터 그룹을 연결하면 된다.

AWS 콘솔로 들어가서 파라미터 그룹을 생성하자.

설정하기

파라미터 그룹 생성하기

RDS 서비스의 오른쪽 메뉴탭에서 파라미터 그룹을 클릭한다.

클릭하면 아래와 같은 화면으로 이동한다. 여기에서 파라미터 그룹 생성을 클릭한다.

RDS > 파라미터 그룹 > 사용자 지정 파라미터 그룹

클릭하면 아래와 같이 파라미터 그룹 생성 화면이 나온다.

RDS > 파라미터 그룹 > 파라미터 그룹 생성

파라미터 그룹 이름, 설명을 입력하자. 파라미터 그룹 패밀리는 엔진 유형을 선택하면 입력이 활성화된다. 네 개 옵션을 모두 선택하고 나면 아래 화면처럼 유형 옵션이 나타난다.

RDS > 파라미터 그룹 > 파라미터 그룹 생성 - 파라미터 그룹 세부 정보

DB 파라미터 그룹 유형을 선택하는 것인데, 파라미터 그룹을 적용할 DB 유형에 맞춰서 선택하면 된다.

DB Cluster parameter group: 클러스터에 포함된 모든 인스턴스에 적용됨 → 클러스터수준
DB parameter group: 개별 인스턴스에 적용 → 인스턴스 수준

다 설정하고 나면 생성 버튼을 클릭한다. 아래 화면에서 생성한 파라미터 그룹을 확인할 수 있다.

RDS > 파라미터 그룹

Timezone 설정하기

생성한 파라미터 그룹의 이름을 클릭하면 파라미터 설정을 변경할 수 있는 화면으로 이동한다. 편집을 클릭한다.

편집을 클릭하면 수정 상태로 바뀐다. 검색창에서 `time_zone`을 입력하고, `값`을 `Asia/Seoul`로 입력한다. 그리고 변경 사항 저장을 클릭한다.

RDS > 파라미터 그룹 > 파라미터 그룹 수정

Encoding 설정하기 (한글 사용 기준)

이번에는 character set을 설정한다. 다시 편집을 클릭하고 검색창에서 `character_set`를 입력한다. 검색하여 나온 모든 항목의 값을 `utf8mb4`로 설정한다(이모지 입력이 필요 없다면 utf8로도 괜찮다). 설정 후 변경 사항 저장을 클릭한다.

이번에는 collation을 설정한다. `character set`이 글자 자체에 대한 모양과 인코딩에 대해 정의한다면, `collation`은 정해져 있는 인코딩을 기반으로 글자끼리 어떻게 비교할지 정의한 규칙이다.

동일한 문자에 대해 어떻게 비교할지, 정렬을 어떻게 할지, 문자열 함수의 결과는 어떻게 달라지는지, 검색 시 어떤 결과를 줄지 등 규칙이 다르게 정의되어 있다.

편집을 클릭하고, 검색창에서 `collation`을 입력한다. 결과로 나온 항목인 `collation_connection`, `collation_server`의 값을 `utf8mb4_general_ci`로 변경한다.

utf8mb4 charset 기준으로 선택할 수 있는 collation은 아래 화면에서 볼 수 있다시피 꽤나 다양한데, `general_ci`로 선택한 이유가 있다.

utf8mb4 charset collation

collation은 검색 및 정렬뿐만 아니라 유니크 인덱스와 같은 다른 부분에서도 사용되는데 이때 한글 데이터가 있는 경우 주의해야 한다. 한글을 포함한 동아시아 언어 등을 서비스한다면 정확한 검색 처리를 위해 `utf8mb4_general_ci`로 설정해야 한다. 예시로 MySQL의 default collation인 `0900_ai_ci`는 한글의 자음과 모음, 일본어의 가타카나와 히라가나를 같은 문자열로 인식하여 처리한다. 따라서 한글 데이터 등을 처리한다면 꼭 `general_ci`로 설정하자.

이제 변경 사항을 저장하고, RDS 데이터베이스 화면으로 이동한다.

DB 인스턴스와 파라미터 그룹 연결하기

수정하고자 하는 DB 인스턴스를 선택하고 수정을 클릭한다.

RDS 데이터베이스

추가 구성 > 데이터베이스 옵션에 DB 파라미터 그룹을 설정하는 부분이 있다. 방금 생성한 파라미터 그룹을 선택한다.

추가 구성 > 데이터베이스 옵션 > DB 파라미터 그룹

계속을 클릭하고, 아래 화면의 수정 예약에서 원하는 옵션 클릭, DB 인스턴스 수정을 클릭하면 끝이다.

참고

[Network] STOMP와 SockJS

jaamong — Fri, 24 Jan 2025 09:42:58 +0900

Spring 환경에서 STOMP 프로토콜을 사용하여 일대일 실시간 채팅을 구현해야 하는 일이 있었는데, 잘 알지도 못하고 설정에 SockJS 활성화를 추가했다. 클라이언트인 Flutter는 `StompClient` 라이브러리와 `ws` 프로토콜로 서버에 연결 요청을 시도했으나 계속 실패했다. 개발 시간이 촉박해서 제대로 STOMP와 SockJS에 대해 공부하지 않았던 탓에 계속 오류를 뿜어댔다...

아래는 Flutter에서 Spring 서버로 연결 시도 시 실패했던 Spring, Flutter 코드이다.

Spring Boot 3.4.1

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        ...
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/stomp") // create connection - ws://domain:port/stomp
                .setAllowedOriginPatterns("*")
                .withSockJS();
    }
}

`registerStompEndpoints`에서 `registry`에 체이닝(chaining)으로 `withSockJS()`를 추가한 부분이 포인트이다. 해당 함수를 추가하면 `SockJS` 사용이 활성화된다.

Flutter 3.5.4

class ChatService {
  static const baseUrl = 'YOUR_BASE_URL'; // e.g., 'http://your-domain:port'
  late StompClient stompClient;
  final Function(String) onMessageReceived;
  final int userId;

  ChatService({required this.userId, required this.onMessageReceived}) {
    _initializeStompClient();
  }

  void _initializeStompClient() {
    stompClient = StompClient(
      config: StompConfig(  // 여기를 주목!
        url: '${baseUrl.replaceFirst('http', 'ws')}/stomp',
        onConnect: onConnect,
        onDisconnect: (f) => print('Disconnected'),
        onWebSocketError: (dynamic error) => print(error.toString()),
        stompConnectHeaders: {'userId': userId.toString()},
        webSocketConnectHeaders: {'userId': userId.toString()},
      ),
    );
  }
  ...

`_initializeStompClient()`의 `config` 설정을 `StompConfig()`로 한 것과 `URL`의 `scheme`을 `http`에서 `ws`로 교체하여 서버에 연결을 시도하는 것이 주목해야 하는 점이다.

이번에는 STOMP와 SockJS가 무엇인지 알아보고, 어떻게하면 연결이 성공하는지 알아보자.

STOMP와 SockJS

프레임, 패킷
https://ict-story.tistory.com/39

프레임(Frame)

프레임은 데이터와 제어정보를 합친 것으로, 다양한 프로토콜들에 의해 교환되고 운반되는 데이터 단위를 뜻한다.
OSI 7계층 중 데이터링크 계층(Data Link layer, Layer 2)에서 정의된다.
일반적인 프레임 구성 형태

패킷(Packet)

패킷은 데이터를 일정 크기로 자른 것으로, OSI 7 계층 중 네트워크 계층(Network layer, Layer 3)에서 정의되는 데이터 단위이다.
그 외에도 OSI의 각 계층에서 주고받는 정보의 단위를 모두 패킷이라고 총칭하기도 한다.

1. 기본 개념

`Frame` ↔ `Framing`

SockJS framing은 클라이언트와 서버 간 전송되는 메세지를 다루고 캡슐화하기 위한 전체적인 메커니즘 또는 구조를 의미한다. 통신이 SockJS 프로토콜을 준수하는지 확인하여 다양한 전송 방법(웹소켓, HTTP Streaming, long polling, etc.) 간의 호환성을 지원한다.
다음 문맥에서는 SockJS 프레임(개별 통신 단위)의 형식을 지정, 전송, 해석하는 방법을 제어하는 프로세스 또는 방법론을 의미한다.

SockJS frame은 SockJS 프로토콜 내의 단일 통신 단위이다. 통신을 통해 전송된 실제 메세지나 컨트롤 패킷을 나타내며 다음의 것들이 포함되어 있을 수 있다; Initialization data, Heartbeat signals, Actual application data
프레임은 일반적으로 SockJS의 특정 형식 규칙을 준수한다. 예를 들어, 페이로드를 JSON 형태로 캡슐화하거나 메시지 유형을 구별하기 위해 헤더를 추가하여 규칙을 준수한다.

SockJS framing은 메세지 패키징, 전송 및 해석을 위한 프로토콜 레벨의 프로세스를 설명하는 더 넓은 개념이고, SockJS frame은 framing 규칙에 따라 형식이 지정되고 전송되는 메시지의 특정 인스턴스다.

SockJS

웹소켓을 사용할 수 없을 때 대체 매커니즘(fallback mechanism)을 제공하는 웹소켓 에뮬레이션(emulation) 라이브러리이다.
- 따라서 Internet Explorer와 같은 레거시 브라우저나 제한적인 네트워크 환경에서 신뢰할 수 있는 전송을 보장할 수 있다.
- Provided Fallback Mechanism Ex. XHR streaming, long polling, …
웹소켓으로 연결을 처음 시도하고, 실패하면 HTTP 기반의 전송으로 대체한다.
클라이언트와 서버 간의 호환성을 위해 메세지에 SockJS 관련 프레이밍(framing)을 추가한다.

STOMP

웹소켓이나 SockJS와 같은 전송을 통한 구조화된 통신을 위한 메시지 프로토콜이다.
애플리케이션 계층에서 메세지 교환 규칙을 정의한다.

2. SockJS와 STOMP가 함께 동작하는 방식

SockJS: 웹소켓으로 첫 연결을 시도하고, 필요한 경우 HTTP 기반의 전송으로 대체하는 전송 메커니즘을 처리한다.
STOMP: 구조화된 메세지 호환성을 제공하기 위해 SockJS 또는 웹소켓 위에서 동작한다.

3. Configuration 기반 동작

Case 1. Spring 서버에서 SockJS 활성화

예상되는 동작
- 클라이언트가 웹소켓이나 HTTP을 통해서 통신을 하는 것과 상관없이, 서버는 모든 통신에 대해서 SockJS 관련 프레이밍을 예상한다.
- SockJS는 웹소켓으로 통신을 시도하고 실패하면 HTTP 통신으로 대체한다.
Flutter 클라이언트 시나리오
1. SockJS를 활성화하고 `ws` 프로토콜을 사용하는 경우
  - 결과: 프로토콜 미스매치로 인한 연결 실패
  - 원인: SockJS 프레이밍을 예상했으나, 원시 웹소켓 핸드셰이크가 전송됨
2. SockJS를 활성화하고 `http` 프로토콜을 사용하는 경우
  - 결과: 성공
  - 원인: SockJS는 전송 폴백을 관리하고 서버가 예상한 값에 맞춰 조정
3. SockJS를 비활성화하고 `ws` 또는 `http` 프로토콜을 사용하는 경우
  - 결과: SockJS 프레이밍의 부재로 인한 실패
  - 원인: 서버에서 연결을 거절함

Spring 서버에서 SockJS 활성화 시 Flutter 클라이언트 시나리오

Case 2. Spring 서버에서 SockJS 비활성화

예상되는 동작
- 서버가 원시 웹소켓으로 동작한다.
- HTTP 전송과 같은 대체(fallback) 메커니즘을 지원하지 않는다.
Flutter 클라이언트 시나리오
1. SockJS를 비활성화하고 `ws` 프로토콜을 사용하는 경우
  - 결과: 성공
  - 원인: 직접적인 WebSocket 연결과 서버가 기대한 값이 일치함
2. SockJS를 활성화하고 `ws` 또는 `http` 프로토콜을 사용하는 경우
  - 결과: 성공
  - 원인: SockJS 프레이밍과 서버의 원시 웹소켓 구현이 호환되지 않음
3. SockJS를 비활성화하고 `http` 프로토콜을 사용하는 경우
  - 결과: 실패
  - 원인: 일반 HTTP는 원시 웹소켓 서버에서 지원되지 않음

Spring 서버에서 SockJS 비활성화 Flutter 클라이언트 시나리오

4. 특정 Configuration의 성공 또는 실패 이유

✅ Flutter에서 SockJS 활성화 시 `ws` 연결이 실패하는 이유

SockJS를 활성화한 클라이언트는 SockJS 프레이밍이 포함된 핸드셰이크를 전송한다.
원시 `ws://` 요청은 SockJS 협상(negotiate)을 우회하여, SockJS를 활성화한 Spring 서버와의 프로토콜 미스매치를 발생시킨다.

✅ Flutter에서 SockJS 활성화 시, `http` 연결이 성공하는 이유

SockJS는 대체 매커니즘의 일부인 `http://`를 사용한다.
클라이언트는 SockJS가 전송을 협상하고 서버와 조율할 수 있도록 한다.

위 문맥에서 협상(negotiate)의 의미

클라이언트와 서버 간의 통신에 가장 적합한 전송 방법을 결정하고 합의하는 과정

Step 1. 최선의 옵션으로 시작하기 (웹소켓)
SockJS는 첫 연결 시도를 웹소켓으로 한다. 이는 가장 효과적이고 선호되는 전송 방법이기 때문이다.

Step 2. 필요하면 대체하기
웹소켓이 안된다면 SockJS는 `HTTP streaming`이나 `long polling`과 같은 전송 방법들을 시도한다.
이때 웹소켓 연결 실패 원인에는 네트워크 제한, 오래된 브라우저, 프록시 등이 있다.

Step 3. 전송 방법 확정하기
SockJS는 사용할 수 있는 최선의 방법을 결정하고 해당 방법을 통신에 사용하도록 클라이언트와 서버를 모두 조정한다.

위 내용을 바탕으로 다시 설정을 해보자.

Spring

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

    @Override
    public void configureMessageBroker(MessageBrokerRegistry registry) {
        ...
    }

    @Override
    public void registerStompEndpoints(StompEndpointRegistry registry) {
        registry.addEndpoint("/stomp") // create connection - ws://domain:port/stomp
                .setAllowedOriginPatterns("*")
                .withSockJS();
    }
}

처음과 동일하게 SockJS를 활성화시킨 코드이다.

Flutter

class ChatService {
  static const baseUrl = 'YOUR_BASE_URL'; // e.g., 'http://your-domain:port'
  late StompClient stompClient;
  final Function(String) onMessageReceived;
  final int userId;

  ChatService({required this.userId, required this.onMessageReceived}) {
    _initializeStompClient();
  }

  void _initializeStompClient() {
    stompClient = StompClient(
      config: StompConfig.sockJS(  // sockJS 추가됨
        url: '$baseUrl/stomp',  //http 또는 https 사용
        onConnect: onConnect,
        onDisconnect: (f) => print('Disconnected'),
        onWebSocketError: (dynamic error) => print(error.toString()),
        stompConnectHeaders: {'userId': userId.toString()},
        webSocketConnectHeaders: {'userId': userId.toString()},
      ),
    );
  }
  ...

처음 코드와 달리 `StompConfig`에 `sockJS`가 추가되었고, URL도 `ws`로 대체하는 것이 아닌 `http`를 그대로 사용하도록 했다.

처음 Flutter 코드처럼 `sockJS`를 사용하지 않을 거라면 Spring 설정에서 `withSockJS()`를 제거하고, Flutter URL의 scheme도 `ws`를 사용하면 된다.

연결 성공!

[Kotlin] 기본 문법 2

jaamong — Sun, 19 Jan 2025 13:43:27 +0900

if

코틀린의 `if`문은 표현식(expression)으로, 아래와 같은 방식으로 변수에 값으로 할당될 수 있다. (삼항연산자를 풀어서 쓰는 느낌이다)

fun main() {
    
    val a: Int = 100
    val b: Int = 200
    val c: Int
    
    c = if (a >= b) {
        a
    } else {
        b
    }
    
    println(c)
}

`null` 체크는 다음과 같이 할 수 있다.

fun main() {
    
	val a: Int? = null
    
	if (a == null) {
            println("null check true")  // print 
	} else {
            println("a = $a")  // a에 null이 아닌 값이 담긴 경우, a에 할당된 값이 출력됨. ex) a = 100
	}

}

in

`in` 연산자를 사용하여 변수에 할당된 값이 주어진 범위에 속하는지 알 수 있다.

fun main() {
    
	val a: Int? = 100
    
	if (a in arrayOf(100, 200, 300)) {
	    println("contained")  // print
	} else {
	    println("not contained")  // a에 할당된 값이 배열에 없는 값이면, not contained 가 출력된다.
	}

}

when

다음 `if-else`문과 `when`문은 동일한 의미이다. (swtich-case문 같기도...)

fun main() {
    
	val a: Int? = 100
    
	when (a) { 
	    100 -> println("1")  // print
	    200 -> println("2")
	    300 -> println("3")
	    else -> println("4")
	}

	if (a == 100) {
	    println("1")  // print
	} else if (a == 200) {
	    println("2")
	} else if (a == 300) {
	    println("3")
	} else {
	    println("4")
	}

}

또한 `when`문에서 범위를 지정할 수 있다.

fun main() {
    
	val a: Int = 399
    
	when (a) {
   	    in 100..199 -> println("1")  // 100 <= a <= 199
  	    in 200..299 -> println("2")  // 200 <= a <= 299
 	    in 300..399 -> println("3")  // 300 <= a <= 399
  	    else -> println("4") 
	}

// 399가 출력됨

}

참고로 nullable 한 변수를 대상으로 실행하면 다음과 같은 에러가 발생한다.

Incompatible types 'kotlin.Int?' and 'kotlin.ranges.IntRange'.

Class / Data class / Enum class

fun main() {
    
    val item1: Item1 = Item1("BOOK", 10_000)  // Item1 클래스의 인스턴스 생성
    println("Item1 name is ${item1.name}, price is ${item1.price}")
    println(item1)

    val item2: Item2 = Item2("BOOK", 10_000) // Item2 데이터 클래스의 인스턴스 생성
    println("Item2 name is ${item1.name}, price is ${item1.price}")
    println(item2)
}

// 기본적으로 생성자가 생성됨
class Item1(val name: String, val price: Int) 

// 기본적으로 getter, setter, Equal, hashCode, toString, Copy, Component, and 함수들이 생성됨
data class Item2(val name: String, val price: Int)

enum class Color {
    RED,
    GREEN,
    BLUE,
}

# 위 코드 실행 결과
Item1 name is BOOK, price is 10000
Item1@133314b
Item2 name is BOOK, price is 10000
Item2(name=BOOK, price=10000)

Data class

코틀린의 `Data class`는 자바의 `Record`와 유사하게 사용할 수 있는 듯하다. → Ex. `DTO` 역할
위와같이 `Data class`를 정의하고 변수를 var로 선언하면 `setter`가 자동으로 생성된다.
- `val`로 선언한 경우, 특성상 변수를 변경할 수 없기 때문에 `setter`가 생성되지 않는다.
- 실행결과를 보면 `Data class`는 클래스 정의 시 `toString`이 자동 생성되므로, 출력했을 때 초기화한 인스턴스 값이 나오는 것을 확인할 수 있다.

[Kotlin] 기본 문법 1

jaamong — Sat, 18 Jan 2025 09:08:48 +0900

요즘 스프링 개발 환경에서도 코틀린을 사용하는 경향이 꽤 보인다. 그래서 코틀린에 관심이 생겨서 찾아본 기본 문법!

변수 타입

코틀린에는 `var`와 `val`라는 두 가지 형태의 변수가 존재한다.

`var`: 초기화 이후에도 값 변경이 가능한 가변 변수
`val`: 초기화 이후에는 값을 변경할 수 없는 불변 변수

fun main() {
    
    var a = 1  
    a = 2  // 가변 변수이므로 값 변경 가능
    val b = 1
    b = 2  // 불변 변수이므로 에러 발생

    var c: Int  // 타입은 명시했으나, 초기화 하지 않은 상태
    println(c)  // 초기화 하지 않은 상태이므로 에러 발생

    c = 1  // 초기화
    println(c)  // 1 출력
}

타입 추론(Type Inference)

타입 추론이란 변수나 함수를 선언할 때 타입을 명시적으로 선언하지 않아도 자동으로 자료형을 추론해 주는 기능이다. 코틀린은 기본적으로 이러한 타입 추론을 지원하므로, 변수를 초기화할 때 명시적으로 타입을 입력하지 않아도 된다. 하지만 협업 시에는 가급적 타입을 명시하는 것이 좋다고 한다.

fun main() {
    
    var a = 1  // int로 타입 추론
    var a: Int = 1 // 타입 명시
}

null과 ?

코틀린 변수는 기본적으로 non-null 타입으로, 위와 같이 선언하여 `null`을 할당하면 에러가 발생한다. `null`을 허용하려면 아래와 같이 선언해야 한다.

fun main() {
    
    var str1: String? = null  // str1 변수에는 String이나 null이 들어올 수 있다
    val str2: String? = null
    var str3: String = null  // non-null 타입이므로 에러 발생

    var i: Int? = null // i 변수에는 Int나 null이 들어올 수 있다
}

Null Safe Operator `?.`

이번에는 문자열의 길이를 출력해 보자.

fun main() {
    
    var str: String? = "test"
    println(str.length)  // 에러 발생: Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'kotlin.String?'.
}

# 위 코드 실행 결과 (에러 발생)
Only safe (?.) or non-null asserted (!!.) calls are allowed on a nullable receiver of type 'kotlin.String?'.

에러를 해석하면 `String?` 타입에서 `null`을 허용하려면 `?.`나 `!!.` 호출이 필요하다는 것 같다.

fun main() {
    
    var str: String? = "test"
    println(str?.length)  // 4
}

`str` 변수와 `.` 사이에 `?`를 붙이면 성공적으로 실행이 된다. 정확히는 `?.`에 의해 성공한 것인데, 이는 `str`이 `null`이 아닌 경우에 `?.` 뒤에 있는 명령어를 실행할 수 있게 한다. 이때 쓰인 `?.`는 `null safe operator`라고 한다.

fun main() {
    
    var str: String? = null
    println(str?.length)  // null 출력
}

`?.` 앞에 위치한 `str` 변수의 값이 `null`이므로 뒤에 있는 `length` 명령어는 실행하지 않으며, `null`이 출력된다.

Not Null Assertion Operator `!!.`

방금 위에서 봤던 에러 문구 중에는 `!!.`도 있었는데, 이는 좌항이 절대 `null`이 아님을 보장한다.

fun main() {
    
    var str: String? = "test" 
    println(str!!.length)  // 4

    var str2: String? = null
    println(str2!!.length)  // str2가 non-null임을 보장 -> null에서 length를 구하는 것이므로 NullPointerException 에러 발생
}

Elvis Operator `?:`

엘비스 연산자는 좌항이 `null`인 경우 우항에 있는 명령어를 실행한다.

fun main() {
    
    var str1: String? = null
    str1 ?: println("str is null")  // "str is null" 출력

    var str2: String? = "not null"
    str2 ?: println("str is null")  // 아무것도 출력되지 않는다.
}

[AWS & Docker] Docker 컨테이너 로그를 AWS CloudWatch로 보내기

jaamong — Sat, 4 Jan 2025 16:39:33 +0900

기존에는 EC2 우분투 환경에서 운영되는 프로그램들의 로그를 AWS CloudWatch에 전송할 수 있도록, 우분투에서 CloudWatch Agent 패키지를 설치하고 관련 설정을 진행했다.

이번에는 EC2(마찬가지로 우분투 환경)에서 Docker 컨테이너로 띄운 프로그램의 로그를 AWS CloudWatch에 전송할 수 있도록 설정을 해보자.

관련 공식 자료는 여기를 참고하자. (딱히 좋은 글인 것 같지는 않다...)

Credentials

EC2 상에서 운영되는 Docker 컨테이너의 로그를 AWS CloudWatch에 전송하기 위해서는 `awslogs` 로깅 드라이버를 사용해야 한다. 이를 위해 자격 증명(credentials)이 필요하며, 해당 자격 증명을 Docker 데몬에 전달해야 한다. 자격 증명이 필요한 이유는 EC2에 CloudWatch에 접근할 수 있는 역할(Role)을 부여해야 하기 때문이다.

제공할 수 있는 자격 증명은 다음과 같다.

`AWS_ACCESS_KEY_ID`
`AWS_SECRET_ACCESS_KEY`
`AWS_SESSION_TOKEN`
기본 AWS 공유 자격 증명 파일(root 사용자의 `~/.aws/credentials`)

또는 AWS EC2 인스턴스 상에서 Docker 데몬을 실행하고 있다면, EC2 인스턴스 프로필로 충분한 것 같다(이 부분은 정확히 어떻게 번역을 해야 할지 모르겠다).

Instance Profile

인스턴스 프로필은 IAM Role(역할)을 저장하는 컨테이너로, EC2 인스턴스를 시작하면 인스턴스 프로필을 읽어서 설정된 IAM Role을 작동시킨다. 예를 들어, A 리소스에 접근가능한 IAM Role을 갖고 있는 인스턴스 프로필이 있다고 하자. 해당 인스턴스 프로필을 EC2에 연결하면 A 리소스에 접근할 수 있다.

이러한 이유로 Docker 데몬이 실행되고 있는 EC2에 인스턴스 프로필이 연결되어 있다면, 충분한 자격 증명이 되는 것 같다.

IAM Role(역할)

IAM Role은 계정에서 생성할 수 있는 특정 권한을 가진 임시 자격 증명이다. 권한은 AWS에서 제공하고 있는 클라우드 서비스와 그 서비스로 할 수 있는 작업, 행동에 관한 범위를 의미한다. IAM Role의 권한은 IAM Policy(정책)에 JSON 형식으로 정의된 문서로, 정책에 나열된 서비스와 작업에 의해 부여된다.

IAM Role 생성

AWS 콘솔에 접속 후 IAM 서비스로 이동한다.

그림 1. IAM 서비스

IAM 대시보드의 왼쪽 메뉴에서 액세스 관리 > 역할을 클릭한다.

그림 2. 액세스 관리 > 역할

역할 생성 버튼을 클릭한다. 클릭 시 역할을 생성하기 위한 화면으로 이동한다.

그림 3. 역할 생성

1단계 신뢰할 수 있는 엔터티 선택은 생성할 IAM역할을 연결할 수 있는 서비스 또는 사용자 계정 등을 의미한다. 아래 신뢰할 수 있는 엔터티 유형 중에서 AWS 서비스를 선택한다.

그림 4. 1단계 - 신뢰할 수 있는 엔터티 선택1

사용 사례 - 서비스 또는 사용 사례에서 EC2를 선택하고, 선택 후 나오는 사용 사례에서 EC2를 선택한다. 이후 하단의 다음을 클릭한다.

그림 5. 1단계 - 신뢰할 수 있는 엔터티 선택2

다음을 클릭하면 2단계 화면으로 넘어간다. 2단계에서는 IAM Role에 IAM Policy를 추가하여 권한을 부여한다. Docker 공식 문서에서는 `logs:CreateLogStream`과 `logs:PutLogEvents` 정책을 적용해야 한다고 한다. 아래 화면에서 필터를 걸어 검색하니 나오지 않아서, 우선 여기서는 정책을 추가하지 않고 다음으로 넘어갔다.

그림 6. 2단계 - 권한 추가

다음으로 넘어가면 3단계가 나온다. 여기에서는 IAM 역할에 이름을 지정하고 설명과 태그를 추가할 수 있다. 이름은 해당 역할이 어떤 목적으로 생성되었는지 설명할 수 있도록 짓는다. 이후 아래로 스크롤을 내려 역할 생성을 클릭한다.

그림 7. 3단계 - 이름 지정, 검토 및 생성

이후 생성한 역할을 클릭하고, 아래 권한 정책에서 권한 추가 > 인라인 정책 생성을 클릭한다.

그림 8. 권한 추가 > 인라인 정책 생성

아래와 같이 권한 지정 화면이 나오면, JSON 형식으로 정책을 편집할 수 있도록 JSON을 클릭한다.

그림 9. 권한 지정 - 정책 편집

그리고 아래와 같이 Action에 Docker 공식 문서에서 지정한 정책을 추가한다. 이후 스크롤을 내려 다음을 클릭한다.

그림 10. Action

다음을 클릭하면 방금 정의한 정책을 검토하는 화면이 나온다. 틀린 부분이 없다면 변경 사항 저장을 클릭한다.

그림 11. 검토 및 저장

이제 생성한 역할을 Docker 데몬이 실행되고 있는 EC2에 연결해야 한다. EC2 서비스로 이동한다. 역할을 연결할 EC2를 선택하고 작업 > 보안 > IAM 역할 수정을 클릭한다.

그림 12. 작업 > 보안 > IAM 역할 수정

아래 화면에서 방금 생성한 IAM 역할을 선택하고 IAM 역할 업데이트를 클릭한다.

지금까지는 로그를 AWS CloudWatch로 보내는 역할과 정책을 설정했다. 이제 받은 로그를 보관할 공간을 생성하자.

CloudWatch

CloudWatch로 이동하여, 왼쪽 메뉴에서 로그 > 로그 그룹을 클릭한다.

로그 그룹 화면에서 로그 그룹 생성을 클릭한다.

아래 화면에서 로그 그룹 이름을 설정하고, 보존 설정은 원하는 대로 설정하면 된다. 다만 저장된 로그 용량이 크면 요금이 청구될 수 있다. 이 부분은 정확하지 않으니, 찾아보고 적절한 기간을 설정하자. 이름과 보존 설정 이후 스크롤을 내려 생성 버튼을 클릭한다.

방금 생성한 로그 그룹을 클릭하고 아래를 보면 로그 스트림 탭이 있다. 로그 스트림 생성을 클릭한다.

그룹 내에서 각 도커 컨테이너 또는 프로그램 별 로그를 식별할 수 있는 이름을 지정하고 Create을 클릭한다.

이제 AWS 설정은 완료되었다.

Docker

EC2 인스턴스 상에서 실행되는 Docker 컨테이너의 docker-compose.yml에 아래와 같이 내용을 추가한다.

version: '3'

services:
  app:
    ...
    logging:
      driver: awslogs
      options:
        awslogs-group: "CloudWatch에서 설정한 로그 그룹 이름"
        awslogs-region: "EC2 인스턴스가 존재하는 리전"
        awslogs-stream: "로그 그룹 내에서 생성한 로그 스트림 이름"

위와 같이 설정하고 컨테이너를 다시 빌드하면 된다.

이후 5~10분 정도 기다리고, AWS CloudWatch에서 `awslogs-group`에 입력한 로그 그룹 > `awslogs-stream`에 입력한 로그 스트림으로 이동하면 컨테이너 로그를 확인할 수 있다.

참고

[Spring Security] OAuth2 카카오 로그인 구현 with JWT

jaamong — Sun, 29 Dec 2024 15:43:53 +0900

⚠️이 포스트는 지식 공유보다는 본인이 나중에 다시 보기 위해 작성하는 기록용입니다...

build.gradle

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    ...
}

application.yml

spring:
  security.oauth2:
    client.registration:
      kakao:
        client-name: Kakao
        client-id: ${CLIENT_ID}
        client-secret: ${CLIENT_SECRET}
        client-authentication-method: client_secret_post
        redirect-uri: ${REDIRECT_URI}
        authorization-grant-type: authorization_code
        scope:
          - account_email
    client.provider:
      kakao:
        authorization-uri: https://kauth.kakao.com/oauth/authorize
        token-uri: https://kauth.kakao.com/oauth/token
        user-info-uri: https://kapi.kakao.com/v2/user/me
        user-name-attribute: id

Spring Security에서 제공하는 OAuth2 기능을 사용한다면 yml 또는 properties 파일에 OAuth2 클라이언트, 서버 정보를 작성해야 한다.

`spring.security.oauth2.client.registration.{registrationId}`
`spring.security.oauth2.client.provider.{registrationId}`

Getting Started ❘ Spring Boot and OAuth2

SecurityConfig

@Configuration
@EnableMethodSecurity
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {

    private final String[] PERMIT_ALL_URL = {
            "/favicon.ico/**",
            "/h2-console/**",
            "/api/health/**",
            "/api/users/login",
            "/api/users/access-token",
            "/oauth2/authorization/kakao",
    };

    private final CorsConfig corsConfig;

    private final JwtAuthenticationFilter jwtAuthenticationFilter;
    private final AuthenticationEntryPoint authenticationEntryPoint;
    private final AccessDeniedHandler accessDeniedHandler;

    private final OAuth2UserService<OAuth2UserRequest, OAuth2User> customOAuth2UserService;
    private final AuthenticationSuccessHandler customOAuth2SuccessHandler;
    private final AuthenticationFailureHandler customAuthExceptionHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
                .csrf(AbstractHttpConfigurer::disable)
                .cors(cors -> cors.configurationSource(corsConfig.corsConfigurationSource()))
                .headers(headers -> headers.frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin))
                .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(req -> req
                        .requestMatchers(PERMIT_ALL_URL).permitAll()
                        .requestMatchers(CorsUtils::isPreFlightRequest).permitAll()
                        .anyRequest().authenticated()
                )
                .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
                .exceptionHandling(e -> e
                        .authenticationEntryPoint(authenticationEntryPoint)
                        .accessDeniedHandler(accessDeniedHandler)
                )
                .oauth2Login(config -> config
                        .userInfoEndpoint(endpointConfig -> endpointConfig
                                .userService(customOAuth2UserService))
                        .successHandler(customOAuth2SuccessHandler)
                        .failureHandler(customAuthExceptionHandler)
                );

        return http.build();
    }
}

별도로 설정하지 않는 한, 클라이언트의 카카오 로그인 요청은 `/oauth2/authorization/kakao` 경로로 들어온다.

The `OAuth2AuthorizationRequestRedirectFilter` uses an `OAuth2AuthorizationRequestResolver` to resolve an `OAuth2AuthorizationRequest` and initiate the Authorization Code grant flow by redirecting the end-user’s user-agent to the Authorization Server’s Authorization Endpoint.

The primary role of the `OAuth2AuthorizationRequestResolver` is to resolve an `OAuth2AuthorizationRequest` from the provided web request. The default implementation `DefaultOAuth2AuthorizationRequestResolver` matches on the (default) path `/oauth2/authorization/{registrationId}`, extracting the registrationId, and using it to build the `OAuth2AuthorizationRequest` for the associated ClientRegistration.

Initiating the Authorization Request, Authorization Grant Support, Spring Docs

CustomOAuth2FailureHandler

@Slf4j
@Component
public class CustomOAuth2FailureHandler implements AuthenticationFailureHandler {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Override
    public void onAuthenticationFailure(HttpServletRequest request, HttpServletResponse response, AuthenticationException exception) throws IOException {
        log.info("[CustomOAuth2SuccessHandler.onAuthenticationFailure] oauth2 authentication fail");
        configureResponse(response);
        objectMapper.writeValue(response.getWriter(), makeResponseBody(exception));
    }

    private ResponseDto<String> makeResponseBody(AuthenticationException exception) {
        String message = "카카오 로그인에 실패했습니다. (exception = " + exception + ") ";
        return new ResponseDto<>(HttpStatus.UNAUTHORIZED, message);
    }

    private void configureResponse(HttpServletResponse response) {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        response.setStatus(HttpStatus.UNAUTHORIZED.value());
    }
}

로그인 요청이 들어왔을 때 인증에 실패하면 `AuthenticationFailureHandler` 필터가 호출된다.
해당 필터는 `SecurityFilterChain`에 등록된 `OAuth2Login` 용도의 `userService`보다 앞에 위치한다.
여기에서 발생한 에러는 `AuthenticationEntryPoint`에서 처리되며, 이는 `@RestControllerAdvice`가 적용된 클래스에서 처리할 수 있다.

CustomOAuth2UserService & OAuth2CustomUser

@Slf4j
@Service
@Transactional
@RequiredArgsConstructor
public class CustomOAuth2UserService extends DefaultOAuth2UserService {

    private final UserRepository userRepository;

    @Override
    public OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {
        try {
            log.info("[CustomOAuth2UserService.loadUser] receive oauth2 login request");

            // obtain user info from the provider using access token
            Map<String, Object> originAttributes = super.loadUser(userRequest).getAttributes();

            // OAuth2 서비스 id (kakao, ...)
            String registrationId = userRequest.getClientRegistration().getRegistrationId();

            // Provider 에서 제공하는 attribute 추출
            OAuthAttributes attributes = OAuthAttributes.of(registrationId, originAttributes);
            String email = attributes.email();

            // 회원 가입 또는 로그인
            registerIfNewUser(email);

            List<SimpleGrantedAuthority> authorities = UserRole.CUSTOMER.getAuthorities();
            return new OAuth2CustomUser(authorities, originAttributes, "id", email);
        } catch (RuntimeException e) {
            log.error("[CustomOAuth2UserService.loadUser] exception = ", e);
            throw new OAuth2AuthenticationException(e.getMessage());
        }
    }

    private void registerIfNewUser(String email) {
        Optional<UserEntity> optionalUser = userRepository.findByUsername(email);

        // 이미 등록된 사용자면 패스
        if (optionalUser.isPresent()) return;

        // 등록된 사용자가 아니면 저장
        UserEntity user = UserEntity.builder()
                .username(email)
                .userRole(UserRole.CUSTOMER)
                .build();

        userRepository.save(user);
    }
}

public record OAuth2CustomUser(
        List<SimpleGrantedAuthority> authorities,
        Map<String, Object> attributes,
        String registrationId,
        String email) implements OAuth2User, Serializable {

    @Override
    public Map<String, Object> getAttributes() {
        return this.attributes;
    }

    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return this.authorities;
    }

    @Override
    public String getName() {
        return this.registrationId;
    }
}

`DefaultOAuth2UserService`는 `OAuth2UserService`의 구현체로 표준 OAuth2.0 공급자를 지원한다.
- 인증을 진행하기 위한 인증 서버(카카오)와 사용자를 저장하기 위한 데이터베이스를 호출하기 위해 `OAuth2UserService`를 구현한다.
구현체에서는 사용자가 정의한 `User` 객체를 상속하고 `OAuth2User`를 구현한 것을 반환해야 한다.

How to Add a Local User Database

Many applications need to hold data about their users locally, even if authentication is delegated to an external provider. We don’t show the code here, but it is easy to do in two steps.

1. Choose a backend for your database, and set up some repositories (using Spring Data, say) for a custom `User` object that suits your needs and can be populated, fully or partially, from external authentication.

2. Implement and expose `OAuth2UserService` to call the Authorization Server as well as your database. Your implementation can delegate to the default implementation, which will do the heavy lifting of calling the Authorization Server. Your implementation should return something that extends your custom `User` object and implements `OAuth2User`.

Hint: add a field in the `User` object to link to a unique identifier in the external provider (not the user’s name, but something that’s unique to the account in the external provider).

Getting Started | Spring Boot and OAuth2

CustomOAuth2SuccessHandler

@Slf4j
@Component
@RequiredArgsConstructor
public class CustomOAuth2SuccessHandler implements AuthenticationSuccessHandler {

    @Value("${oauth2.login.redirect-url}")
    private String redirectURL;

    private final UserService userService;

    @Override
    public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response, Authentication authentication) throws IOException {
        log.info("[CustomOAuth2SuccessHandler.onAuthenticationSuccess] oauth2 authentication success");

        OAuth2CustomUser oAuth2User = (OAuth2CustomUser) authentication.getPrincipal();
        String email = oAuth2User.email();

        // issue a refresh token
        UserEntity user = userService.getByUsername(email);
        ResponseCookie responseCookie = userService.authenticate(user);

        // configure HttpServletResponse
        log.info("[CustomOAuth2SuccessHandler.onAuthenticationSuccess] Redirect URL = {}", redirectURL);
        configureResponse(response, responseCookie);
        response.sendRedirect(redirectURL);
    }

    private void configureResponse(HttpServletResponse response, ResponseCookie cookie) {
        response.setContentType(MediaType.APPLICATION_JSON_VALUE);
        response.setCharacterEncoding(StandardCharsets.UTF_8.name());
        response.setStatus(HttpStatus.OK.value());
        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
    }
}

`CustomOAuth2UserService`가 성공하면 `SuccessHandler`로 넘어오게 된다.
- 로그인에 성공했으므로 리프레시 토큰을 발급한다.
- 발급한 리프레시 토큰은 쿠키에 담아서 전달한다.
  - 쿠키 설정 시 CORS를 고려하여 주의해야 할 점이 있다.
```
ResponseCookie.from("refresh_token", refreshToken)
    .httpOnly(true)
    .secure(true) 
    .maxAge(600) // 10분
    .sameSite(Cookie.SameSite.NONE.attributeValue())
    .path("/")
    .build();
```
  - 백엔드 서버에 HTTPS를 적용했다면 `secure`와 `sameSite`를 위 코드처럼 설정하고, HTTP면 `secure`를 `false`로, `sameSite`를 `LAX`로 설정해야 한다.
`CustomOAuth2UserService`에서 반환했던 `OAuth2User`를 `authentication.getPrincipal()`로 꺼낼 수 있다.
위 클래스까지 통과하면 카카오 로그인 과정이 성공적으로 처리된 것이다.

이후 과정

클라이언트는 쿠키에 담긴 리프레시 토큰을 가지고 서버에게 액세스 토큰 발급을 요청한다.

[Spring] @Value과 static 변수

jaamong — Mon, 16 Dec 2024 21:06:22 +0900

일반적으로 Spring 애플리케이션에서 application.yml에 정의된 값을 static 변수에서 사용할 수 없다. 따라서 Spring에서 제공하는 `@Value` 애노테이션으로 설정 파일에 정의된 값을 static 변수에 주입하면 에러가 발생한다.

Java의 static 변수는 아래 시점에 메모리에 저장된다.

스프링 컨테이너(Application Context)가 로드되기 전 == 객체 생성 이전 == 의존성 주입을 받기 전

하지만 `@Value`는 의존 관계 주입 시점(인스턴스 수준)에서 동작한다. 이로 인해 의존성 주입을 받기 전에 메모리에 저장되는 static 변수에는 값을 주입할 수 없다. 이는 더 나아가서 클래스 레벨에도 동일하게 적용할 수 있다.

`@Component` 애노테이션이 적용되지 않은 클래스는 컴포넌트 스캔 대상에 포함되지 않으므로 스프링 빈으로 등록되지 않는다. 따라서 스프링 빈으로 등록되어 있지 않은 클래스에서 static 변수가 아니더라도 `@Value`로 값을 주입받으면 동일한 에러가 발생할 수 있다.

일반적인 주입 방법이 아닌 다른 방법을 사용하면 static 변수에 설정 값을 주입할 수 있다.

@PostConstruct

`@PostConstruct`가 적용된 메서드는 모든 빈 초기화 직후에 호출이 된다. 이를 이용하여 인스턴스 변수에 주입된 값을 static 변수에 할당할 수 있다.

@Component
public class DemoConfig {

    @Value("${demo.config.property}")
    private String demoProperty; // 인스턴스 변수인 여기에 먼저 주입
    
    public static String STATIC_DEMO_PROPERTY; 
    
    @PostConstruct // 빈 초기화 이후 호출되어, 인스턴스 변수에 주입된 값을 static 변수에 할당
    public void setup() {
    	STATIC_DEMO_PROPERTY = demoProperty;
    }
}

Setter

setter 메서드를 이용하여 static 변수에 값을 할당할 수 있다. 이전 방법과 달리 Spring이 값을 주입할 때 static 변수에 값을 바로 할당할 수 있다.

@Component
public class DemoConfig {

    private String demoProperty;
    
    public static STATIC_DEMO_PROPERTY;
    
    @Value("@{demo.config.property}")
    public setDemoProperty(String demoProperty) {
    	DemoConfig.STATIC_DEMO_PROPERTY = demoProperty;
    }
}

잊기 전에 남겨두는 Amazon API Gateway 사용 이유

jaamong — Sat, 30 Nov 2024 09:07:17 +0900

AWS Lambda 사용법을 조사하다가 Amazon API Gateway가 같이 언급되는 글이 많길래 왜 그런가 찾아봤다. 결론은 Lambda가 특별히 API Gateway가 필요해서 같이 붙어 다니는 건 아니었다.

Lambda는 특성상 무거운 프로그램의 서버보다는, 한 가지 목적에 집중하는 가벼운 프로그램의 서버로 적합하다. 각 기능(인증, 스케쥴링, 모니터링 등)을 여러 개의 Lambda로 분리해서 API Gateway로 연결하는 편이 좋다.

다음은 API Gateway를 사용했을 때 얻을 수 있는 이점이다.

Reusability

Lambda 유무와 관계없이 API Gateway를 사용하면 새 프로젝트 시작할 때마다 인증 기능을 구현할 필요도 없다. 인증 기능이 배포된 서버를 API Gateway에 연결해서 사용하면 되기 때문이다.

예를 들어, 클라이언트가 게이트웨이에서 한 번 인증을 하면, 인증된 요청들은 적절한 백엔드로 라우팅 된다. 따라서 각 백엔드는 인증을 처리할 필요가 없다.

Decoupling Clients from the Backend → Abstracting Backend Infrastructure

또한 API Gateway은 클라이언트 요청에 대해 단일 도메인을 제공하므로, 클라이언트는 각 기능이 배포된 서버의 endnpoint를 알 필요가 없다. 오로지 API Gateway의 도메인만 알면 된다.

[Spring Data JPA] 하이버네이트 Batch Size

jaamong — Mon, 25 Nov 2024 16:42:04 +0900

상황

1:N 관계가 얽혀있는 엔티티를 대상으로 Spring Data JPA를 이용해서 Pagination 조회를 하니 말로만 듣던 N+1 상황이 발생했다.

처음에는 일반적인 해결 방법인 Fetch Join을 사용하려고 했다. 더불어 중복을 방지하기 위해 `DISTINCT` 추가하려고 했다. 그러나 1:N 관계의 컬렉션을 Fetch Join 하면서 동시에 Pagination을 사용하는 것은 OutOfMemoryError가 발생할 수 있고, 이로 인해 `DISTINCT`를 적용할 수 없다고 한다. 그래서 찾은 다른 방법 중 가장 빠르고 쉬운 방법은 Batch Size를 설정하는 것이었다.

하이버네이트 Batch Size

하이버네이트에서 제공하는 `@BatchSize` 애노테이션이나 `batch_size`을 적용하여 Batch Size을 설정할 수 있다.

엔티티를 가져오는 것은 데이터베이스에서 데이터를 가져와 애플리케이션에서 객체(Object)로 변환하는 것을 의미한다. 하이버네이트는 데이터를 그룹(batches)으로 가져와 이런 동작을 최적화할 수 있다. 이는 데이터베이스 호출 수를 줄이고, 요청 처리 효율성을 증가시킨다.

클래스 레벨에서 적용하기

엔티티 클래스에 `@BatchSize(size=n)`을 적용하면 하이버네이트는 지연 로딩 동안 해당 엔티티의 인스턴스를 한 번에(한 요청) 최대 n개까지 가져오도록 지시한다. 이는 많은 연관된 엔티티들을 가져올 때 매우 효과적으로 데이터베이스 쿼리의 수를 줄일 수 있다.

@Entity
@BatchSize(size=100)
public class MyEntity {
    ...
}

컬렉션 레벨에서 적용하기

엔티티의 컬렉션 필드에 `@BatchSize`를 설정하면 해당 컬렉션의 요소를 배치 사이즈만큼 일괄적으로 가져와 지연 로딩 처리가 최적화된다. 이 또한 데이터베이스 쿼리 수를 줄이고 관련 컬렉션에 접근할 때 성능을 향상한다.

@OneToMany
@BatchSize(size=50)
private Set<MyCollection> myCollections = new HashSet<>();

스프링 부트에서 `batch_size` 설정하기

`batch_size` 파라미터 설정을 통해 insert, update, delete 작업에도 batch size를 적용할 수 있다. 해당 파라미터는 `application.properties` 또는 `application.yml`에서 쉽게 설정할 수 있다.

spring.jpa.properties.hibernate.jdbc.batch_size=50

하이버네이트에서 이러한 쓰기 작업을 최적화하는 것은 오직 전역 `batch_size` 설정을 통해서만 할 수 있다. `@BatchSize` 애노테이션은 오로지 읽기 작업에만 영향을 미친다.

해결

나는 읽기 작업 외에 쓰기(save/saveAll) 작업에도 적용되길 원했기 때문에 `application.yml`에 `batch_size` 설정을 하여 해결했다. (보통 전역적으로 설정할 때 size는 100 이상으로 하는 것 같다)

번외. Batch Insert와 MySQL

Notice 여기서 부터는 1:N 관계 Pagination의 N+1 문제와는 관련이 없다.

참고로 Batch Insert를 원하는데, MySQL을 사용하고 있고 PK 생성 전략을 `IDENTITY`로 하고 있다면 위 설정 외에도 추가적으로 해야 할 것이 있다. 그렇지 않으면 Spring Data JPA의 `saveAll()`을 쓰든 `batch_size`를 사용하든 데이터 건 수 별로 단건 insert 호출이 발생한다. 이유는 PK 생성 전략을 `IDENTITY`로 설정한 경우 하이버네이트에서 Batch Insert 기능을 지원하지 않기 때문이다.

MySQL에서 IDENTITY 전략은 `AUTO_INCREMENT`로 PK 값을 자동 증가시켜 생성하는 것이다. 이는 insert 작업을 실제로 실행하기 전까지는 ID에 할당된 값을 알 수 없음을 의미하며, Transaction Write-Behind를 할 수 없어 Batch Insert 작업을 실행할 수 없는 결과를 초래한다.

이를 해결하는 방법 중 하나는 PK 생성 전략을 `IDENTITY` 대신 `SEQUENCE`나 `TABLE` 전략으로 변경하는 것이다. 하지만 이런 방법은 기존 데이터베이스 설계에 영향을 줄 수 있을 것 같아서 다른 방법을 찾았다. 바로 JDBC Template를 사용하는 것이다.

Batch Insert와 JDBC Template 사용하기

JDBC Template을 사용하여 Batch Insert를 하려면 MySQL JDBC에 `rewriteBatchedStatements` 옵션을 추가하여 `true`로 설정해야 한다. JDBC Template 의존성은 Spring Data JPA를 사용중이라면 바로 import 할 수 있다.

spring:
  datasource:
    url: jdbc:mysql://{MYSQL_DB_URL}:{PORT}/{SCHEMA}?rewriteBatchedStatements=true

이제 `JdbcTemplate`을 사용하여 Batch Insert를 해보자!

@Repository
@RequiredArgsConstructor
public class MyEntityJdbcRepository {

    private final JdbcTemplate jdbcTemplate;

    public void saveAll(List<MyEntity> myEntities, Long myEntityLastId) {
        String sql = "INSERT INTO my_entity (my_entity_id, ..., created_at, modified_at) VALUES (?, ..., now(), now())";

        jdbcTemplate.batchUpdate(sql, new BatchPreparedStatementSetter() {
            @Override
            public void setValues(PreparedStatement ps, int i) throws SQLException {
                MyEntity myEntity = myEntities.get(i);

                // 파라미터 설정
                ps.setLong(1, myEntityLastId + i); // pk 설정
                ps.setString(2, myEntity.getXxx());
               	...
                ps.setString(n, myEntity.getXxx());
            }

            @Override
            public int getBatchSize() {  
                return myEntities.size();  // 삽입할 컬렉션 크기 만큼 배치 사이즈 설정
            }
        });
    }
}

이제 insert/save 로직을 수행하는 곳에서 해당 메소드를 호출하여 사용하면 된다.

잘 적용이 되었는지 콘솔창에서 확인하고 싶다면 아래 설정을 추가하자.

spring:
  datasource:
    url: jdbc:mysql://{MYSQL_DB_URL}:{PORT}/{SCHEMA}?rewriteBatchedStatements=true&profileSQL=true&logger=Slf4JLogger&maxQuerySizeToLog=500

`profileSQL=true` : Driver에서 전송하는 쿼리를 출력
`logger=Slf4JLogger` : Driver에서 쿼리 출력 시 사용할 Logger 설정
`maxQuerySizeToLog=...` : 출력할 쿼리 길이 설정

Batch Insert 이후 또다른 문제...

Batch Insert를 사용한 `saveAll()` 이후 JPA를 이용한 단건 insert/save 작업에서 문제가 발생했다(둘은 별도의 트랜잭션에서 실행된다). 에러를 보니 PK 위반 문제였는데, 원인은 `SEQUENCE/IDENTITY` 생성에 관한 하이버네이트의 이해와 데이터베이스 상태 사이의 불일치 때문이었다.

`jdbcTemplate.batchUpdate()`는 레코드를 바로 삽입하고 `AUTO_INCREMENT` 값을 증가시킨다.
하이버네이트의 `save()`는 JDBC가 이미 사용한 최신 `AUTO_INCREMENT` 값을 인지하지 못한다.
MySQL은 내부적으로 `AUTO_INCREMENT` 카운터를 유지하려고 한다.

그래서 JDBC를 사용한 Batch Insert 이후에 MySQL의 `AUTO_INCREMENT` 값을 데이터베이스에 마지막으로 저장된 값보다 더 큰 값으로 업데이트하도록 로직을 수정했다.

@Repository
@RequiredArgsConstructor
public class MyEntityJdbcRepository {

    private final JdbcTemplate jdbcTemplate;

    public void saveAll(List<MyEntity> myEntities, Long myEntityLastId) {
        ...
    }
    
    // 데이터베이스 id의 가장 마지막 값을 조회
    public Long getMaxId() {
        String sql = "SELECT COALESCE(MAX(my_entity_id), 0) FROM my_entity";
        return jdbcTemplate.queryForObject(sql, Long.class);
    }

    // 다음 ID를 `value`로 시작하도록 테이블 변경
    public void resetAutoIncrement(Long value) {
        String sql = "ALTER TABLE my_entity AUTO_INCREMENT = ?";
        jdbcTemplate.update(sql, value);
    }
}

실제 사용 코드이다. Batch Insert 이후 ID 값을 업데이트 한다(단일 insert/save 하는 코드 쪽은 건드리지 않았다).

@Transactional
public void initData() {
    ...
    myEntityJdbcRepository.saveAll(myEntities, 1L);

    Long maxId = myEntityJdbcRepository.getMaxId();
    myEntityJdbcRepository.resetAutoIncrement(maxId + 1);
}

이후 정상적으로 실행됐다!

참고

[Java Error] Caused by: java.lang.IllegalArgumentException at PropertyPlaceholderHelper.java:180

jaamong — Sat, 23 Nov 2024 13:57:29 +0900

Gradle로 테스트를 빌드하다가 제목과 같은 에러를 만났다.

사실 처음에는 그냥 빌드하다가 위와 같은 정확한 에러명이 나오지 않아서 나중에 빌드할 때 아래 명령어를 사용했다. 그냥 빌드했을 때 실패했다고만 나오면 해당 옵션으로 시도하는 것을 추천한다

./gradlew test -i  # 윈도우 gitbash에서 실행

Note `-i / --info` 옵션은 로그 레벨을 INFO로 설정하는 것이다.

에러 내용을 봤을 때 yml/properties 파일에 작성한 프로퍼티 설정을 가져오면서 뭔가 문제가 있는 것 같았다. 그리고 역시나 `@Value`로 yml에 적힌 값을 가져올 때 오타가 있었다. 이 부분을 수정하고 다시 빌드하니 해당 에러는 더 이상 보이지 않았다! (관련 없는 다른 에러가 반겨주었다...)

별거 아닌 내용이었지만 정리하는 이유는 테스트를 빌드하다가 위 에러를 처음 만났기도 했고, 처음 써본 gradle 옵션을 남겨두고 싶어서다. 저 옵션을 몰라서 계속 그냥 빌드하다가 오랜 시간 삽질을 했던... 삽질 기록기...

Java/Spring 테스트 - 2

jaamong — Mon, 4 Nov 2024 20:42:26 +0900

지난 포스팅에 이어서 작성합니다.

2024.10.02 - [Java] - Java/Spring 테스트 - 1

의존성

의존성

컴퓨터 공학에서 말하는 의존성(Dependency)은 결합(Coupling)과 같은 의미로, 다른 객체의 함수를 사용하는 상태를 말함 ⇒ A는 B를 사용하기만 해도 의존한다고 할 수 있음
의존성을 약하게 만드는 기술 중 하나가 의존성 주입
- 필요한 값을 `new`해서 직접 인스턴스화하는 것이 아닌 외부에서 넣어주는 것
  - `new`를 이용하여 인스턴스화 하는 것은 하드 코딩
- 의존성 주입은 의존성을 약화시키는 것, 의존성을 완전히 없애는 방식이 아님
- 의존성 제거 == 객체 간의 협력 부정 / 시스템 간의 협력 부정
- 대부분의 디자인 패턴이나 설계는 어떻게 하면 의존성을 약화시킬 수 있는지 고민한 결과물

의존성 역전

의존성 역전(DI) ≠ 의존성 주입(DIP)
- Dependency Inversion ≠ Dependency Injection Principle
DIP
- 의존성 역전이란?
  1. 상위 모듈은 하위 모듈에 의존해서는 안된다. 상위 모듈과 하위 모듈 모두 추상화에 의존해야 한다.
  2. 추상화는 세부 사항에 의존해서는 안된다. 세부 사항이 추상화에 의존해야 한다.
- 다형성의 원리 중 하나
- 모듈 간의 상하 관계를 포함하는 개념
- 화살표의 방향을 바꾸는 기술
- 의존성 역전은 고수준 코드에서 세부 사항에 의존해서는 안됨 <RF. 로버트. C. 마틴 저, 클린 아키텍처>
- `import`에 사용되는 경로에는 인터페이스나 추상 클래스만을 사용해야 함
- 인터페이스나 추상 클래스 같은 추상적인 선언을 정책으로 볼 수 있고, 변동성이 큰 구체적인 요소를 세부 사항으로 볼 수 있음

의존성과 테스트 (의존성과 테스트의 상관관계)

테스트를 잘하려면 다음의 것을 잘 다룰 수 있어야 한다.

의존성 주입
의존성 역전

예시 | 마지막 로그인 시간

가정 사용자가 로그인할 때마다, 마지막 로그인 시간을 기록해야 함

class User {

	private long lastLoginTimestamp;
	
	public void login() {
		// ...
		this.lastLoginTimestamp = Clock.systemUTC().millis();
	}
}

의존성이 숨겨져 있는 경우에 해당
- 내부 로직에서 `login`은 `Clock`에 의존적
- 하지만 외부에서 `login` 함수를 호출할 때는 `login`함수가 `Clock`을 사용하는지 모르기 때문
일반적으로 의존성이 숨겨져 있으면 좋지 않은 신호
```
class UserTest {

    @Test
    public void login_테스트() {
        // given
        User user = new User();
				
        // when
        user.login();
				
        // then
        assertThat(user.getLastLoginTimestamp()).isEqualTo(???);
    }
}
```
- 마지막으로 로그인한 시간을 비교해야 하는데 `???`에는 어떤 값이 들어가야 하는지 알 수 없음
- `login`을 호출한 시간과 결과를 비교하는 시점의 시간은 다를 수밖에 없음 → 테스트 방법 X
  - 시간을 강제로 stub 해 주는 라이브러리가 있지만, 너무 부자연스러움 → 라이브러리가 없으면 테스트가 불가능함
- 이러한 코드를 테스트하는 것은 불가능하고 일관되게 유지하는 것도 어려움
⇒ 이런 식으로 테스트 코드를 작성하면서 ‘이건 테스트가 불가능한데?’, ‘테스트가 mock 프레임워크 없이는 불가능한데?’ 라면 생각한다면, 이는 테스트가 보내는 신호!

예시의 문제점 해결

1. 의존성 주입으로 해결 - 시계를 외부에서 주입받는 경우

class User {

    private long lastLoginTimestamp;
	
    public void login(Clock clock) {
        // ...
        this.lastLoginTimestamp = clock.millis();
    }
}

class UserTest {

    @Test
    public void login_테스트() {
        // given
        User user = new User();
        Clock clock = Clock.fixed(Instant.parse("시간"), ZoneId.of("UTC"));
				
        // when
        user.login(clock);
				
        // then
        assertThat(user.getLastLoginTimestamp()).isEqualTo(milliseconds로 환산한 시간);
    }
}

필요한 값을 만들고, 그 값을 `login`에 전달함. 그다음 결과 값을 지정한 시간과 비교함.

알게 된 점

숨겨진 의존성은 테스트하기 힘들게 만든다.
의존성은 드러내는 것이 좋다.

문제점

외부에서 주입받아 해결했는데, 결국 `login`을 사용하는 곳에서도 `Clock`이라는 숨겨진 의존성을 사용해야 함

class UserService {
		
    public void login(User user) {
        // ...
        user.login(Clock.systemUTC()); // 숨겨진 의존성인 Clock 사용 
    }
}

따라서 `UserService` 테스트가 어려워짐
```
class UserServiceTest {
	
    @Test
    public void login_테스트() {
        //given
        User user = new User();
        UserService userService = new UserService();
				
        //when
        userService.login(user);
				
        //then
        assertThat(user.getLastLoginTimestamp()).isEqualTo(???);
    }
}
```
- 이를 해결하기 위해 또 다른 의존성 주입을 사용하는 것은 해결방법이 아님 → `UserService`를 사용하는 또 다른 코드에 `Clock`이 숨겨지는 결과. 결국 어딘가에서는 고정된 값을 입력하여 넣어줘야만 함 → 또 테스트하기 힘들어짐 ⇒ 폭탄 돌리기

2. 의존성 역전으로 해결 - 현재 시간을 알려주는 인터페이스 정의

interface ClockHolder {
    long getMillis();
}

@Getter
class User {
    private long lastLoginTimestamp;
		
    public void login(ClockHolder clockHolder) {
        // ...
        this.lastLoginTimestamp = clockHolder.getMillis();
    }
}

@Service
@RequiredArgsConstructor
class UserService {

    private final ClockHolder clockHolder;
		
    public void login(User user) {
        // ...
        user.login(clockHolder);
    }
}

`User`는 이제 `Clock`이 아닌 `ClockHolder`에 의존
`ClockHolder`는 외부에서 주입받도록 함
`UserService`는 `ClockHolder`를 멤버 변수로 받도록 되어 있음
- 유저가 로그인할 때 `clockHolder` 값을 건네줌

장점

우선 `ClockHolder`의 두 가지 구현체를 생성해 보자.

@Component
class SystemClockHolder implements ClockHolder {
		
    @Override
    public long getMillis() {
        return Clock.systemUTC().millis();
    }
}

실제 배포 환경에서 사용할 `SystemClockHolder`
현재 시간을 요청하면 시스템 시간을 반환

@AllArgsConstructor
class TestClockHolder implements ClockHolder {

    private Clock clock;
		
    @Override
    public long getMillis() {
        return clock.millis();
    }
}

위 구현체는 객체를 생성할 때 `Clock`을 받도록 함

실제 테스트

class UserServiceTest {

    @Test
    public void login_테스트() {
        // given
        Clock clock = Clock.fixed(Instant.parse("시간"), ZoneId.of("UTC"));
        User user = new User();
        UserService userService = new UserService(new TestClockHolder(clock));
				
        // when
        userService.login(user);
				
        // then
        assertThat(user.getLastLoginTimestamp()).isEqualTo(milliseconds로 환산한 시간);
    }
}

`UserService`를 생성할 때 `TestClockHolder`를 주입
- `User`가 받게 될 `ClockHolder`는 지정한 `Clock`만 내려주는 `ClockHolder`가 될 것
배포 환경에서는 어떨까?
- `SystemClockHolder`는 스프링 빈으로 등록되어 있기 때문에 스프링이 `UserService`를 만들 때 알아서 잘 주입해 줄 것.
결과적으로 의존성 주입과, 의존성 역전 기술 모두 사용함
- 의존성 역전을 사용했을 뿐인데, 배포 환경과 테스트 환경을 분리할 수 있게 됨 ⇒ 추상화 의존 결과
  - 의존성 역전 `Port-Adapter 패턴`으로도 부름

Testability

Testability는 테스트 가능성으로, 얼마나 쉽게 input을 변경할 수 있고, 얼마나 쉽게 output을 검증할 수 있는가를 의미한다.

얼마나 쉽게 Input을 변경...

Case1.1 - 의존성이 감춰져 있는 경우
```
class User {

    private long lastLoginTimestamp;
		
    public void login() {
        // ...
        this.lastLoginTimestamp = Clock.systemUTC().millis();
    }
}
```
- 위처럼 `Clock`같은 감춰진 의존성이 존재한다면 input을 외부에서 변경할 수 없음 ⇒ testability가 낮은 코드
Case1.2 - Input이 숨겨져 있는 경우
```
@Getter
@Builder(access = AccessLevel.PRIVATE)
@RequiredArgsConstructor
public class Account {
		
    private final String username;
    private final String authToken;
		
    public static Account create(String username) {
        return Account.builder()
            .username(username)
            .authToken(UUID.randomUUID().toString())
            .build();
    }
}
```
테스트 코드 1
```
class AccountTest {

    @Test
    void create() {
		
        //given
        String username = "foobar";
				
        // when
        Account account = Account.create(username);
				
        // then
        assertThat(account.getUsername()).isEqualTo("foobar");
    }
}
```
- `username` 말고도 `authToken`이 잘 생성되었는지 확인해야 함
- `authToken`은 UUID로 생성 — "UUID가 사용된다는 이야기는 처음 듣는데요?" → 숨겨진 input: 호출자는 모르는 정보
  - 호출자가 해당 메서드를 타고 들어와서 내부 알고리즘을 확인함 → 객체지향의 핵심 가치 중 하나인 캡슐화가 깨짐
  - 알고리즘을 확인했어도 만들어진 `authToken` 값이 제대로 된 값인지 확인할 방법이 없음
테스트 코드 2 - mock 프레임워크 이용해 보기: 강제 라이브러리들을 이용해서 지정된 UUID만 내려주도록 바꿔보자.
```
class AccountTest {

    @Test
    void create() {
		
        //given
        String username = "foobar";
        String expectedAuthToken = "...";
        PowerMockito.mockStatic(UUID.class);
        when(UUID.randomUUID()).thenReturn(UUID.fromString(expectedAuthToken));
				
        // when
        Account account = Account.create(username);
				
        // then
        assertThat(account.getUsername()).isEqualTo("foobar");
        assertThat(account.getAuthToken()).isEqualTo(expectedAuthToken);
    }
}
```
- UUID의 `randomUUID()`는 static 메서드
  ⇒ 의존성 역전으로 해결해 보자!
Case 2.1 - 파일 경로 하드 코딩
```
public class Example {
    private static final File FILE = new File("data.txt");
		
    public void processData() {
        //read from FILE and process data
    }
}
```
- File path가 고정되어 있다면, 고정된 파일에 지나치게 의존하게 돼서 input 변경이 힘듦 ⇒ 낮은 Testability

Case 2.2 - 외부 시스템 하드 코딩

public class Example {
    public void processData(String data) {
        String processData = data.toUpperCase(); // 데이터 처리
        sendDataOverNetWork(processedData);
    }
		
    private void sendDataOverNetwork(String data) {
        // HTTP를 이용한 네트워크 요청 
    }
}

스프링을 이용하다 보면 `WebClient`나 `RestTemplate` 같은 통신 클래스를 많이 사용하게 됨 → 이를 직접 사용하고 있을 것 → 테스트 어려움

얼마나 쉽게 output을 검증

Case. 외부에서 결과를 볼 수 없는 경우

public class Example {
    public void processData(int[] numbers) {
        int sum = 0;
        for (int number : numbers) {
            sum += number;
        }
        System.out.println("Sum: " + sum);
    }
}

외부에서 콘솔에 출력된 값이 어떤 값인지 확인할 수 없음 → 결과 확인 불가능 ⇒ 낮은 Testability

[JPA Error] No EntityManager with actual transaction available for current thread - cannot reliably process 'flush' call

jaamong — Wed, 23 Oct 2024 20:04:42 +0900

에러 원인

정말... 바보같은... 실수였다...

오류가 났던 테스트 코드는 아래와 같다.

	...
    
    @PersistenceContext
    EntityManager em;

    @Test
    void test() { 
        UserEntity userEntity = UserEntity.builder()
                .nickname("test")
                .email("test@example.com")
                .build();
        userEntity = userRepository.save(userEntity);
        userService.sumTotalAmount(userEntity, 10_000L);

        Long requestAmount = 5_000L;
        Long updatedAmount = userService.minusTotalAmount(userEntity, requestAmount);

        em.flush();
        em.clear();

        //잘 반영이 되었는지 확인하기 위해 영속성 컨텍스트를 비우고 새로 조회
        UserEntity findEntity = userRepository.findById(userEntity.getId()).get();

        assertThat(updatedAmount).isEqualTo(5_000L);
        assertThat(findEntity.getTotalAmount()).isEqualTo(updatedAmount);
    }

테스트 하고 싶었던 부분은 `minusTotalAmount`가 요청한 만큼 `totalAmount`를 잘 감소시키는 지였다.

우선 `em.flush()`로 쿼리를 날려주고, 영속성 컨텍스트를 비운 상태에서 객체를 새로 조회하기 위해 `em.clear()`를 호출했었다. 그다음 객체를 새로 조회하여 필드에 제대로 값이 반영이 되었는지 검증했다.

그리고 제목과 같은 에러가 발생했다.

번역하자면...

현재 스레드에 사용 가능한 실제 트랜잭션이 있는 EntityManager가 없습니다. 'flush' 호출을 안정적으로 처리할 수 없습니다.

`EntityManager`가 `flush()`를 호출했는데 이를 처리할 Transaction이 없어서 실행할 수 없다는 뜻이다.

JPA는 트랜잭션 단위로 기능을 수행하고, 수행하면서 1차 캐시에 저장된 엔티티들은 DB에 flush되어 영속화된다. 그런데 위 테스트 코드는 트랜잭션이 없기 때문에 위와 같은 에러가 발생했던 것이다.

에러 해결

아주 간단히 해결할 수 있다... 테스트할 메서드나 클래스에 `@Transactional`를 붙여주면 된다!

	...
    
    @PersistenceContext
    EntityManager em;

    @Test
    @Transactional
    void test() { 
        UserEntity userEntity = UserEntity.builder()
                .nickname("test")
                .email("test@example.com")
                .build();
        userEntity = userRepository.save(userEntity);
        userService.sumTotalAmount(userEntity, 10_000L);

        Long requestAmount = 5_000L;
        Long updatedAmount = userService.minusTotalAmount(userEntity, requestAmount);

        em.flush();
        em.clear();

        //잘 반영이 되었는지 확인하기 위해 영속성 컨텍스트를 비우고 새로 조회
        UserEntity findEntity = userRepository.findById(userEntity.getId()).get();

        assertThat(updatedAmount).isEqualTo(5_000L);
        assertThat(findEntity.getTotalAmount()).isEqualTo(updatedAmount);
    }

이제 `flush()`를 호출하고 콘솔창을 확인하면 쿼리가 제대로 나가는 것을 확인할 수 있다^^!

Java/Spring 테스트 - 1

jaamong — Wed, 2 Oct 2024 20:30:14 +0900

이 글은 아래 인프런 강의를 듣고 기록을 남기고자 작성하였습니다.

Java/Spring 테스트를 추가하고 싶은 개발자들의 오답노트 강의 | 김우근 - 인프런

김우근 | Spring에 테스트를 넣는 방법을 알려드립니다! 더 나아가 자연스러운 테스트를 할 수 있게 스프링 설계를 변경하는 방법을 배웁니다., 프로젝트 설계를 발전시키는 테스트의 본질을 짚

www.inflearn.com

TDD

회귀 버그(Regression Bug) → 테스트 자동화
테스트 추가
- 소프트웨어의 내적 품질 향상 O, 사용자가 체감할 수 있는 외적 품질 향상 X
- 가시적 성과 지표 → 커버리지(Coverage)
비결정적인 테스트
- 테스트를 실행할 때마다 테스트 결과가 다름
- 어제는 테스트를 통과했는데 오늘은 통과하지 못하는 경우
레거시 코드에 테스트를 넣는 것 → TDD가 아님
- 레거시 코드에 테스트를 넣기만 하는 것은 크게 의미가 없을 수도
- 레거시 코드에 테스트를 넣는 과정은 코드 개선을 하면서 진행해야 의미가 있다 (외부 시스템 의존도 ↓ & 설계 진화)
커버리지 집착 X
- 생각보다 테스트가 필요 없는 코드가 있을 수도 있다. 커버리지 목적이 아닌, 테스트를 추가했을 때 얻을 수 있는 효용성에 집중하자.
✅테스트가 줄 수 있는 가치
- 회귀 버그 방지
- 유연한 설계 (매우 도전적)
  - 테스트가 계속 신호를 보냄
    - 프로젝트가 스프링이나 JPA에 의존적인 상태일 확률 높음
    - 외부 시스템에 의존하는 상황을 피해야 함 → 설계 진화
  - 테스트와 설계는 긴밀한 관계
✅왜 테스트를 해야 하고, 어떻게 해야 하는지 고민할 것
✅방향성 - TDD를 논하기 전에 테스트가 가능한 구조로 변경되어야 함

테스트란

테스트

⇒ 어떤 시스템이 제대로 동작하는지 검증하는 과정

인수 테스트사람이 직접 사용해 보면서 준비된 체크 리스트를 진행하는 테스트
자동 테스트테스트 코드라고 불리는 미리 작성된 코드를 보면서 결괏값과 예상값을 비교하는 테스트
- 주로 `when/given/then` 패턴으로 작성됨

TDD

아래 과정을 무한히 반복

`RED` : 실패하는 테스트를 먼저 작성한다.
- 컴파일되는 코드를 만들고 테스트가 실패하는 것까지 확인해야 함
- 실패하는 테스트를 먼저 작성해야 하므로, 인터페이스를 먼저 만드는 것이 강제됨 → OOP 핵심 원리 중 하나인 행동에 집중하는 것과 동일 ⇒ What/Who 사이클을 고민하게 도와줌
`GREEN` : 위 실패하는 테스트를 성공시킨다.
- 실제로 구현하는 단계
- 이후 테스트를 실행하면 성공
`BLUE` : 리팩토링 한다.

장단점

장기적인 관점에서의 장점이 확실함
- 인터페이스를 먼저 만드는 것이 강제됨
- 개발 비용 감소
장기적으로 봤을 때 장점이 뚜렷하므로 요구사항이 명확하지 않거나, 서비스의 흥망성쇠가 눈에 보이지 않는 경우에는 적용하기 부담스러움(Ex. 스타트업)
적용 난이도 높음

개발자의 고민

무의미한 테스트
- OOP에서 말하는 행동은 메서드나 함수를 의미하는 것이 아니다. 따라서 모든 메서드를 테스트하는 것보다 중요한 로직을 잘 구분하여 해당 코드를 테스트하는 것이 낫다.
테스트가 불가능한 코드
- Ex. 사용자가 로그인하고 마지막 로그인 시간을 기록하는 코드 등...
- 테스트가 불가함 → 설계가 잘못되었을 가능성 높음 ⇒ 설계 발전
느리고 쉽게 깨지는 코드
- 코드 자체는 별 것 아니지만, 실행 시간이 오래 걸리는 경우
  - 100개가 넘어가는 테스트 코드 중에 이와 같은 경우가 있다면 시간적으로 부담됨

테스트 코드의 필요성

좋은 아키텍처란

SOLID와 테스트는 굉장히 긴밀한 상관관계를 갖는다 → 서로에게 상호보완적
`TEST` for 회귀버그 방지 ↔ `SOLID` for 좋은 아키텍처
- SOLID 원칙이 지켜지면 경계가 만들어짐 → 이로 인해 회귀 버그를 막을 수 있음
- 단일 책임 원칙(SRP)
  - 테스트는 명료하고 간단하게 작성해야 하기 때문에, 단일 책임 원칙을 지키게 됨
  - 테스트가 너무 많아져서 어떤 목적의 클래스인지 파악하기 어려운 지점이 생김. 이는 해당 클래스의 책임 과다 문제일 수 있음. → 클래스를 분할해야 하는 시점 ⇒ 자연스러운 책임 분배
- 개방 폐쇄 원칙(OCP)
  - 테스트 컴포넌트와 프로덕션 컴포넌트를 나눠 작성하게 되고, 필요에 따라 이 컴포넌트를 자유자재로 탈부착이 가능하도록 개발하게 됨
- 리스코프 치환 원칙(LSP)
  - 이상적으로 테스트는 모든 케이스에 대해커버하고 있으므로, 서브 클래스에 대한 치환 여부를 테스트가 알아서 판단
- 인터페이스 분리 원칙(ISP)
  - 테스트는 그 자체로 인터페이스를 직접 사용해 볼 수 있는 환경. 불필요한 의존성을 실제로 확인할 수 있는 샌드박스.
- 의존관계 역전 원칙(DIP)
  - 가짜 객체를 이용하여 테스트를 작성하려면 의존성이 역전되어 있어야 하는 경우가 생김

필요성

테스트를 어떻게 바라보냐에 따라 테스트의 가치는 다르게 측정됨
- 낮은 가치: "품질 보증을 위한 도구/회귀 버그 방지"만 바라보고 테스트 코드 작성
- 높은 가치: "회귀 버그 방지"와 "설계를 위한 도구"를 위한 테스트 코드 작성

RF. Effective unit testing

테스트 3분류

단위 테스트 → Small(소형) 테스트 (80%) 중요
- `단일 서버 / 단일 프로세스/ 단일 스레드`에서 실행되는 테스트를 의미
- `Disk IO`와 `Blocking call`이 있으면 안 됨
  - Ex. `Thread.sleep`이 테스트에 있으면 소형 테스트가 아님
- 이러한 조건 때문에, 소형 테스트는 결과가 항상 결정적(Deterministic)이고 테스트 속도가 빠름
  - 이러한 테스트를 여러 개 만들어서 코드 커버리지를 높여야 함
  - 프로젝트에 아직 테스트가 없다면, 소형 테스트를 늘릴 수 있는 환경을 만들고, 소형 테스트를 늘려야 함.
통합 테스트 → Medium(중형) 테스트 (15%)
- 소형 테스트보다 완화된 기준
- `단일 서버 / 멀티 프로세스 / 멀티 스레드` 사용 가능
  - H2와 같은 테스트용 DB 사용 가능
    - 다시 말하면, 소형 테스트에서는 DB(H2) 사용 불가
  - 소형 테스트보다 느림
  - 멀티 스레드 환경에서 어떻게 동작할지 모르기 때문에 결과가 항상 같다는 보장을 할 수 없음
    - 테스트 결과가 H2 같은 외부 모듈의 동작에 따라서 달라짐
API 테스트 → Large(대형) 테스트 (5%)
- `멀티 서버` 가능 → E2E(End to End) 테스트

RF. Software Engineering at Google

개념

SUT

System Under Test
테스트하려는 대상
Ex. 북마크 결과가 제대로 됐는지 기록하는 테스트 코드가 있을 때, `SUT`는 user

BDD

Behaviour driven development (given - when - then 또는 3A)
테스트를 작성하다 보면 어느 순간 "어디에 어떻게 테스트를 넣어야 하지?"라는 질문을 마주하게 된다. 그때 BDD가 "생동에 집중해야 한다"고 알려준다.
유저가 시스템을 사용하는 user story를 강조하고, 시나리오를 강조한다. 이를 지키기 위한 뼈대로 아래와 같은 방식을 사용하라고 권유함
- 어떤 상황이 주어졌을 때(given)
- 이 행동을 하면(when)
- 결과가 이렇다(then)

상호 작용 테스트(Interaction Test)

메서드가 실제로 호출이 됐는지 검증하는 테스트
- 일반적으로, 메서드가 실제로 호출됐는지 검증하는 방법은 좋지 않음
  - 내부 구현을 어떻게 했는지 감시하는 것이므로 ⇒ 캡슐화 위배
- 객체에게 위임한 책임을 해당 객체가 제대로 수행했는지 확인만 하면 되는데 구현에 집착하게 된다.

상태 검증 vs 행위 검증

상태 기반 검증(state-based-verification)
- 어떤 값을 시스템에 넣었을 때, 나오는 결괏값을 기댓값과 비교하는 방식
행위 기반 검증(behaviour-based-verification)
- == 상호 작용 테스트
- 어떤 값을 시스템에 넣었을 때, 협력 객체의 어떤 메서드를 실행하는가
- BDD에서 말하는 `행위`와는 다른 의미. 행위 기반 검증이 BDD를 말하는 것이 아님.

테스트 픽스처

fixture = 비품, 설비
테스트를 하기 위해 필요한 자원이 있다면 미리 생성해 두는 것을 테스트 픽스처라고 함
- `@Before`를 적용한 메서드에 테스트를 하기 위한 `sut`을 미리 생성해 둠 ⇒ `sut = 테스트 픽스처`
테스트 픽스처는 sut가 될 수 있고, sut에 들어가야 하는 의존성 일부가 될 수도 있음.

비욘세 규칙

구글에서 만든 규칙(대중적이지 않음)이지만, 꽤 의미 있는 규칙
"유지하고 싶은 상태나 정책이 있다면, 알아서 테스트를 만들어야 한다."
- 유지하고 싶은 상태가 있으면 전부 테스트로 작성 → 그게 곧 정책이 됨
- 유저 아이디가 이메일 형식이길 원한다면, 유저 아이디가 이메일이 아닐 때 예외를 던지는 테스트를 작성하면 됨
- 마일리지 쿠폰이 5만 원 이상일 때만 사용 가능하게 하고 싶다면, 5만원 미만일 때 예외를 던지는 테스트를 작성하면 됨
협업 시에도 큰 도움이 됨
- 개발 문서보다 더 효율적일 때도 있다.

Testability (다른 글에서 다시 정리)

테스트 가능성. 소프트웨어가 테스트 가능한 구조인가?

Test Double

double == 스턴트맨과 같은 '대역'
회원 가입을 할 때 인증 메일을 보내는 시스템이 있을 때, 회원 가입하는 코드를 테스트할 때마다 인증 메일이 발송되어야 할까? 그럴 수는 없음 → 대신 이메일을 발송하는 부분에 가짜 객체(Test Double)를 넣어준다.

대역 종류

Dummy
- 일을 시켜도 아무런 동작도 하지 않는 객체
Fake
- Dummy와 달리 자체 로직을 갖고 있음
- 회원 가입 메일 내용이 제대로 만들어졌는지 테스트하고 싶음 → Fake 사용
  - 발송한 메시지를 기록하는 로직을 가지고 있음
- 잘 만들어진 Fake는 테스트할 때 말고도, 로컬 개발 시에도 사용할 수 있음

Stub

주로 외부 연동하는 컴포넌트에 많이 사용함

객체에 어떤 일을 시켰을 때 미리 준비된 값을 제공

class SubUserRepository implements UserRepository {
	public User getByEmail(String email) {
		if (email.equals("foo@bar.com")) {
			return User.Builder()
					.email("foo@bar.com")
					.status("PENDING")
					.build();
			}
		throw new UsernameNotFoundException(email);
	}
}

보통 `mokito` 프레임워크를 이용하여 구현됨

//given
given(userRepository.getByEmail("foo@bar.com")).willReturn(User.builder())
		.emamil("foo@bar.com")
		.status("PENDING")
		.build();
// when
// ...

// then
// ...

Mock
- 사실상 테스트 더블과 동일한 의미로 사용됨
- stub → mock, dummy → mock, fake → mock으로 부름
- 메서드 호출을 확인하기 위한 객체
Spy
- 모든 메서드 호출을 낱낱이 기록해 두고 있는 객체
  - 메서드가 몇 번 호출됐는지, 잘 호출됐는지 등을 검증

[Gradle] gradle build와 gradle bootJar의 차이

jaamong — Fri, 6 Sep 2024 16:45:11 +0900

`Dockerfile` 안에서 스프링 부트 프로젝트를 `gradlew`로 빌드하려고 찾아보니 `build` 말고 `bootJar`를 추천했다. 이유가 궁금해져서 이렇게 글을 정리하게 되었다.

build

`build`는 Base Plugin이 제공하는 생명주기 작업으로, 대상 소스의 생명주기 확인이나 어셈블 작업을 수행한다. 여기에는 테스트 실행이나 프로덕션 아티팩트 생성 등이 포함되어 있다.

bootJar

`bootJar`는 대상 소스를 실행가능한 `jar` 파일로 빌드하는 것으로, 빌드 속도가 `build` 작업에 비해 빠르고 당연히 생성되는 것도 적다. 이렇게 빌드된 파일은 `build/libs/*.jar`에 위치하게 된다.

이렇게 생성된 파일을 대상으로 `jar -xf {대상 jar 파일}` 명령어를 실행하여 압축을 풀면 `BOOT-INF`, `META-INF`, `org` 폴더가 생긴다.

해당 폴더들이 무엇을 의미하는 지는 여기 링크를 참고하자. 잘 정리되어 있다.

참고

[JPA] 임베디드 타입(@Embeddable, @Embedded)에 관하여

jaamong — Fri, 23 Aug 2024 09:15:30 +0900

@Embeddable, @Embedded

`@Embeddable` 애노테이션이 있는 클래스는 기본 생성자가 필요함
임베디드 타입은 값 타입에 속하는데, 이러한 값 타입은 여러 엔티티에서 공유하면 side effect를 일으킬 수 있다.
- 따라서 불변 객체(Immutable Object)로 설정하여 이러한 문제를 방지하는 것이 좋다.
- `@Embeddable` 클래스에 수정자(setter)를 생성하지 않고 생성자만 두어, 생성자로만 값을 설정하게 한다
  - 수정자가 없으므로 해당 임베디드 값 타입을 필드로 갖고 있는(@Embedded) 엔티티에서는 특정 값만 수정하는 것이 불가능. 객체를 새로 생성해야 함.

public static void main(String args[]) {

    Address address = new Address("city", "zipcode"); //임베디드 값 타입
    
    Member member = new Member(); // 멤버 엔티티
    member.setAddress(address);
    
    //만일 address의 city 값을 수정하고 싶다면 아래와 같이 해야함
    
    Address newAddress = new Address("newCity", "zipcode"); //새로운 객체
    member.setAddress(newAddress);
    
    //Address 클래스에는 수정자가 없고 생성자만 존재하므로, 특정 값만 수정하고 싶어도 위와 같이 새로운 객체를 생성해야 함

}

[Java] new Integer와 Integer.valueOf()의 차이점

jaamong — Sun, 11 Aug 2024 16:55:55 +0900

`new Integer(int)`는 새로운 객체 인스턴스를 매번 생성한다.

`Integer.valueOf(int)`은 지정된 `int` 값을 나타내는 `Integer` 인스턴스를 반환한다.

새로운 `Integer` 인스턴스가 필요한 경우가 아니라면, 일반적으로 생성자 `Integer(int)` 보다 해당 메서드를 우선적으로 사용하는 것이 메모리 측면에서 권장된다. 이는 자주 요청되는 값을 캐싱하여 더 나은 공간 및 시간 성능을 제공할 가능성이 높기 때문이다.

다음은 예시 코드다.

public static void main(String[] args) {
    
    Integer a = new Integer(10);
    Integer b = new Integer(10);
    
    System.out.println("a==b : " + (a==b));
    
    Integer c = Integer.valueOf(10);
    Integer d = Integer.valueOf(10);
    
    System.out.println("c==d : " + (c==d));
}

결과는 아래와 같다.

a==b : false
c==d : true

강의를 듣다가 이야기가 나와서 한 번 알아보았다. 근데 `new Integer(int)` 이 생성자는 버전 9부터 deprecated 상태다. 따라서 해당 버전 이상을 사용할 경우 강제로 `Integer.valueOf(int)` 사용하게 된다 :)

[Spring Boot / Error] Required request body is missing

jaamong — Sat, 13 Jul 2024 09:26:20 +0900

상황

`Required reuqest body is missing`라는 문구와 함께 `HttpMessageNotReadableException` 타입의 에러가 발생했다.

`Controller`에 존재하는 메서드에서 `request body`를 인식하지 못하는 것으로 확인했다.

@RestController
public class RestController {

    @PostMapping("/aaa")
    public ResponseEntity<Void> aaa(@RequestBody @Valid final RequestDto dto) {
				...
        return ResponseEntity.status(HttpStatus.CREATED).build();
    }

		...
}

해당 메서드에 `@RequestBody`를 적용하여 JSON 데이터를 받고 있다. 메서드 내부에서 로그를 찍어봤을 때 해당 값이 잘 넘어오는 것을 확인했으며 디버깅을 했을 때도 존재하는 것을 확인했다. 그러나 반환값이 `201`이 아닌 `403`으로 확인된다.

원인

디버깅을 진행했을 때 직접 작성한 코드 내에서는 반환값이 정상적으로 201로 저장되었다. 그러다가 신기하게도 컨트롤러 전에 이미 거쳤을 `Filter`를 컨트롤러 이후에 또 방문하는 것을 발견했다.

계속 디버깅을 하다 보니 `OncePerRequestFilter`를 상속받는 커스텀 필터인 `JwtAuthenticationFilter`에 문제가 있었다.

Spring에서 모든 요청들은 컨트롤러에 도달하기 전에 Filter, Interceptor 등을 거친다. 직접 정의한 필터도 예외는 아니다.

아래 코드는 직접 정의한 필터이다.

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        if(특정 조건) {
            filterChain.doFilter(request, response); //first doFilter
        }

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {
            ...
        }
        filterChain.doFilter(request, response); //second doFilter
    }

특정 조건인 경우에 토큰 검증 로직을 수행하지 않도록 바로 `doFilter`를 호출하는 코드인데, 여기에 문제가 있었다. 아무리 여기서 `doFilter`를 먼저 호출한다고 해도 결국은 메서드이므로 해당 메서드를 통해 컨트롤러까지 도달하여 나머지 로직을 수행하고 나면 다시 해당 필터로 돌아오게 된다.

실제로 아래와 같이 로깅을 해놓고 문제가 되는 API를 호출하면 다음과 같이 콘솔창에 출력되는 것을 확인할 수 있다.

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        if (특정 조건) {
             log.info("before first doFilter");
             filterChain.doFilter(request, response); //first doFilter
             log.info("after first doFilter");
        }
				
        log.info("here");
				
        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) { //특정 조건의 경우 토큰이 필요없는 요청이므로 통과 못함
            ...
        }
       
        log.info("before second doFilter");
        filterChain.doFilter(request, response); //second doFilter
    }

...
before first doFilter
after first doFilter
here
before second doFilter
...

첫 번째 `doFilter` 이후로도 두 번째 `doFilter`에 방문하는 것을 알 수 있다.

따라서 그다음 로직을 수행하게 되어 가장 아래에 있는 `doFilter`를 거치게 된다. 이렇게 필터를 두 번 거치고 나니 `ResponseEntity`의 `status code`가 `403`으로 변하게 되었다. 내부 로직을 세세하게 보지는 못했으나, 필터를 또 거치면서 어떤 조건을 충족하게 되어 상태 코드가 변한 것 같다.

해결

해결방법은 간단하다. 필터를 두 번 거치지 않도록 하면 되므로 특정 조건의 경우 `doFilter`를 수행하게 했던 코드를 제거한다.

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {
            ...
        }
        filterChain.doFilter(request, response); //second doFilter
    }

기존에 특정 조건을 확인했던 코드는 쓸데없이 검증하지 않도록 작성했던 것이다. 그러나 이미 아래에 `if`문으로 토큰을 확인하며, 반드시 `doFilter`를 수행하므로 해당 코드는 필요가 없는 것으로 판단하여 제거했다.

이후 원하는 대로 정상 작동했다!

참고

https://upcurvewave.tistory.com/614

Java에서 외부 프로그램 실행하기 (zt-exec)

jaamong — Sat, 6 Jul 2024 15:51:11 +0900

프로젝트를 진행하면서 Java 환경에서 Python 프로그램을 실행해야 할 일이 생겼다. 해본 적이 없어서 할 수 있는지가 걱정이었는데 역시 안될 건 없다.

종류

일단 외부 프로그램을 실행할 때 쓰이는 방법들을 찾아보았다.

JSR-233 Scripting Engine
Jython
ProcessBuilder
Apache Common Exec(thrid-party lib)
ZT Process Executor
HTTP (python server)

JSR-233 Scripting Engine

Java 6 부터 지원
set of scripting APIs
`CLASSPATH`에 `Jython`이 있어야 함
- Jython의 경우 파이썬 라이브러리를 한정적으로 사용하게 됨

Jython

자바 코드에 파이썬 코드를 직접적으로 임베딩할 수 있음
- 자바 코드에 파이썬 코드가 섞여서 유지보수가 어려워짐
Jython의 경우 파이썬 라이브러리를 한정적으로 사용하게 됨

ProcessBuilder

자바에서 외부 프로그램을 실행하고 관리하기 위한 도구
작성된 파이썬 파일을 실행하는 방식
`assumption` PATH 변수를 통해 파이썬을 사용할 수 있어야 함
안전하게 스트림을 처리하려면 3~4개 이상의 전용 클래스를 구현해야 함
- "Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the subprocess may cause the subprocess to block, or even deadlock."

Apache Common Exec

ProcessBuilder 코드와 비슷함
작성된 파이썬 파일을 실행하는 방식
일관된 API로 폭넓은 OS를 지원하는 것이 주요 철학

ZT Process Executor

`ProcessBuilder`, `common-exec` 기능 사용 가능
- Improved handling of stream
- One liners to get process output into a String
- Improved logging with SLF4J API
only 3rd-party dependency is SLF4J
깃허브 주소

HTTP

python -m http.server 9000

또는 Flask나 Django를 이용하여 HTTP 통신을 하는 방법

나는 이 중에서 `ZT Process Executor`를 선택했다. 제공하는 기능이 폭넓고 예제 코드도 나와있어서 좋았다. 또한 사용하기 위해 어떤 추가적인 라이브러리 등이 필요하지 않다는 점이 좋았다.

ZT Process Executor

실행될 파이썬 프로그램은 파일을 인자로 받으며, 자바는 파이썬을 호출하고 나서 해당 결과를 파싱 하여 저장한다.

...
public class FileHandler {

    private final FileService fileService;
	...

    public returnType pythonExecutor(MultipartFile file) {

        File saveFile = fileService.saveFile(file);
        String savedPath = saveFile.getSavedPath();
        final String pyPath = "...";

        String[] commands = {"python", pyPath, savedPath};
        String output = null;

        //ZT Process Executor를 이용한 python 파일 호출
        try {
            output = new ProcessExecutor().command(commands)
                    .readOutput(true).execute()
                    .outputUTF8();
        } catch (IOException | InterruptedException | TimeoutException e) {
            log.error("Process Executor Error occur: ", e);
            throw new RuntimeException(e);
        }
        // 결과 파싱
        JSONObject result = parseJson(output);
        String field = result.get("원하는 필드"); //이런식으로 파싱한 결과의 필드를 꺼낼 수 있음
        
		...
    }

    private JSONObject parseJson(String output) {
        final String jsonOuterKey = "field";

        JSONParser parser = new JSONParser();
        JSONObject object;

        try {
            object = (JSONObject) parser.parse(output);
        } catch (ParseException e) {
            log.error("JSON Parse Error occur: ", e);
            throw new RuntimeException(e);
        }

        return (JSONObject) object.get(jsonOuterKey);
    }
}

`parseJson` 메서드에서 `jsonOuterKey`는 이런 경우를 위함이다. 겉에 아무것도 없다면 바로 꺼내면 된다.

"field" : {
	"aaa": ...,
    ...
}

자세한 ZT Process Executor 사용법은 깃허브 링크를 참고!

[TIL / JPA] 데이터베이스 스키마 자동 생성, UNIQUE 제약 조건 관련 TIL

jaamong — Sun, 30 Jun 2024 08:07:10 +0900

JPA 데이터베이스 스키마 자동 생성

개발 서버에서는 가급적 `none`
테스트 서버와 스테이징 서버에 `validate` 정도는 괜찮은 듯. 그래도 가급적 `none`을 권장. 혼자 개발하는 환경에서는 `validate` 정도는 괜찮지만, 여러 명이 함께 개발하는 곳에서는 `none`.
실제 운영서버에서는 아예 `none`. 수많은 데이터가 있는 운영 서버에서 `ALTER` 쿼리 등을 잘못 입력하면 시스템이 중단 상태가 될 수도 있음. 그래서 가급적 작성한 쿼리가 잘 동작하는지 테스트 서버에서 확인해봐야 함.
운영 서버에 스크립트를 반영할 때 가급적이면 쿼리를 다듬어서 넘긴다.

필드와 컬럼 매핑

`@Column`의 `unique=true` 제약 조건은 잘 사용하지 않는다. 사용 시 제약 조건 이름이 랜덤 생성되어 알아볼 수가 없어서 운영 환경에서 좋지 않음.

UNIQUE 제약 조건을 거는 다른 방법은 `@Table(uniqueConstraints)`를 사용하는 것. 이 방식은 이름을 정할 수 있으므로 사용하기 좋다.

출처

인프런 - 김영한님의 자바 ORM 표준 JPA 프로그래밍 기본편

[TIL / JPA] 영속성 컨텍스트

jaamong — Sat, 29 Jun 2024 09:47:10 +0900

이 글은 아래 강의를 바탕으로 공부한 내용을 정리하는 글입니다.

자바 ORM 표준 JPA 프로그래밍 - 기본편 | 김영한 - 인프런

김영한 | JPA를 처음 접하거나, 실무에서 JPA를 사용하지만 기본 이론이 부족하신 분들이 JPA의 기본 이론을 탄탄하게 학습해서 초보자도 실무에서 자신있게 JPA를 사용할 수 있습니다., 실무에서도

www.inflearn.com

영속성 컨텍스트

엔티티를 영구 저장하는 환경
논리적 개념, 눈에 보이지 않음
`EntityManager`를 통해서 접근
- `EntityManager`는 엔티티를 조작하고 데이터베이스와의 통신을 수행하는 인터페이스. 엔티티의 영속성 컨텍스트를 관리하며, 데이터베이스로의 변경사항을 자동으로 동기화함.
`EntityManager`를 생성하면 그 안에 영속성 컨텍스트가 1:1로 생성됨

예제 코드

import jakarta.persistence.*;

import java.util.List;

public class JpaMain {

    public static void main(String[] args) {

        EntityManagerFactory emf = Persistence.createEntityManagerFactory("hello"); 
        EntityManager em = emf.createEntityManager(); 
        
        EntityTransaction tx = em.getTransaction(); //JPA는 반드시 트랜잭션 안에서 작업
        tx.begin();

        try {
            ...
            em.persist(entity);
            tx.commit(); //정상 종료가 되면 커밋
        } catch (Exception e) {
            tx.rollback(); //문제가 생기면 롤백
        } finally {
            em.close(); //작업 종료가 되면 entity manager 닫기
        }

        emf.close(); //애플리케이션이 모두 종료되면 entity manager factory 닫기
    }
}

`EntityManagerFactory`는 애플리케이션(DB) 당 1개만 생성해야 함
`EntityManager`는 고객 요청이 올 때마다 쓰고 닫아야 함
- 주의! 스레드 간에 공유 X → 장애 발생. 사용하고 버려야 함.
`em.persist(entity)`
- 영속성 컨텍스트를 통해서 엔티티를 영속화하는 코드
- 엔티티를 DB에 저장하는 것이 아닌 영속성 컨텍스트에 저장하는 것
`EntityManager`는 데이터베이스 커넥션을 가지고 동작하기 때문에 작업이 끝나면 반드시 닫아줘야 함

엔티티의 상태

비영속

객체 생성 후 `EntityManager`에 넣지 않음. JPA와 전혀 관계없는 상태.

영속

`EntityManager`안에는 영속성 컨텍스트가 있다. `EntityManager.persist(Entity)`를 하면 해당 엔티티가 영속성 컨텍스트에 들어가면서 영속 상태가 된다.

        try {
            // ---비영속 상태---
            Member member = new Member();
            member.setId(1L);
            member.setName("member");

            // --- persist -> 영속 상태 ---
            System.out.println("=== BEFORE ===");
            em.persist(member); //영속성 컨텍스트를 통해서 member 객체가 관리됨. 여기서 insert 쿼리 안나감
            System.out.println("=== AFTER ===");

            tx.commit(); //영속 상태가 되고 바로 DB에 저장되는 것이 아닌 트랜잭션을 커밋하는 시점에 영속성 컨텍스트에 있는 쿼리가 DB로 나감
        }
        ...

준영속 상태

객체를 아래 코드처럼 영속성 컨텍스트에서 지우면(detach) 아무런 관계가 없게 됨

EntityManager.detach(Entity);

Note em.persist()를 해도 영속 상태가 되고, JPA를 통해 조회(em.find()) 했을 때 해당 객체가 영속성 컨텍스트에 없어서 1차 캐시에 넣는 것도 영속 상태가 되는 것

1차 캐시

영속성 컨텍스트는 내부에 1차 캐시를 가지고 있다. 예를 들어 객체를 생성한 상태는 비영속, `EntityManager.persist(Entity)`를 하면 영속 상태가 된다. 이렇게 `EntityManager`를 통해 영속성 컨텍스트에 넣으면 내부에 존재하는 1차 캐시에 엔티티를 넣어둔다.

1차 캐시에서 조회

Member member = new Member();
member.setId("member1");
member.setName("회원1");

//1차 캐시에 저장
EntityManager.persist(member); 
//1차 캐시에서 조회
EntityManager.find(Member.class, "member1");

`EntityManager.find()`를 하면 DB에서 찾는 것이 아닌 먼저 1차 캐시에서 찾는다.

1차 캐시에 찾는 값이 존재하면 DB가 아닌 여기에서 값을 조회한다.
1차 캐시에 없으면 DB에서 조회하고 1차 캐시에 저장한다.
- 이후 해당 객체를 찾으면 1차 캐시에서 조회할 수 있다.

`EntityManager`는 DB 트랜잭션 단위로 생성되고 트랜잭션이 종료되면 EntityManager도 같이 종료된다. 즉, 고객 요청이 들어와서 비즈니스 로직이 끝나면 해당 영속성 컨텍스트를 지운다는 의미이다. 따라서 1차 캐시도 사라지게 된다. 이러한 찰나의 순간에서만 이점이 있다.

엔티티 등록 - 쓰기 지연

영속성 컨텍스트에는 `1차 캐시` 외에 `쓰기 지연 SQL 저장소`라는 것이 있다.

`EntityManager.persist(entity1)`를 하면 1차 캐시에 `entity1`가 들어간다. 동시에 JPA가 해당 엔티티를 분석하여 `INSERT` 쿼리를 생성하고 이를 쓰기 지연 SQL 저장소에 쌓아둔다.

`EntityManager.persist(entity2)`를 하면 1차 캐시에 `entity2`가 들어간다. 동시에 JPA가 해당 엔티티를 분석하여 `INSERT` 쿼리를 생성하고 마찬가지로 이를 쓰기 지연 SQL 저장소에 쌓아둔다.

저장소에 있던 쿼리들은 트랜잭션을 커밋하는 시점에 DB로 날아간다(flush).

쓰기 지연 SQL 저장소에 원하는 만큼 쿼리를 모아서 한 번에 DB에 보내는 방법도 있다. 이를 `JDBC Batch`라고 한다. 하이버네이트에는 아래와 같은 옵션이 있다.

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          batch_size: 100

이렇게 하면 해당 사이즈만큼 쿼리를 모아서 한 번의 네트워크로 DB에 쿼리를 보낸다. (버퍼링 같은 기능)

변경 감지(Dirty Checking)

JPA는 DB 트랜잭션 커밋 시점에 영속성 컨텍스트 내부에 있는 `flush()`라는 것이 호출된다. 이때 엔티티와 스냅샷을 비교한다.

1차 캐시 안에는 PK인 `@Id`와 `Entity`, `스냅샷`이 있다. 스냅샷은 값이 영속성 컨텍스트에 들어온 최초 시점의 상태를 저장해 둔 것이다.

해당 상태에서 엔티티의 값이 변경되면 트랜잭션 커밋 시점에 `flush()`가 호출되면서 JPA가 Entity와 스냅샷을 비교한다. 비교하고 값이 변경되었으면 `UPDATE` 쿼리를 쓰기 지연 SQL 저장소에 둔다. 그리고 해당 쿼리를 DB에 반영하고 커밋하게 된다.

flush

`flush`는 영속성 컨텍스트의 변경 내용을 DB에 반영하는 것으로, 영속성 컨텍스트의 쿼리들을 DB에 날리는 것이다.

`flush`가 발생하면 아래와 같은 일이 일어난다.

DB 트랜잭션이 커밋되면 `flush`가 자동으로 발생
변경 감지(dirty checking)
수정된 엔티티와 관련된 update 쿼리를 쓰기 지연 SQL 저장소에 등록
쓰기 지연 SQL 저장소의 쿼리를 DB에 전송(등록, 수정, 삭제 쿼리 등)

Note flush를 해도 1차 캐시는 유지된다. 영속성 컨텍스트의 변경내용을 DB에 동기화하는 것뿐.

SUMMARY - 배운 것 조합하기

`em.persist()`를 하고 `em.find()`를 바로 호출하면, 영속성 컨텍스트에 있는 데이터를 가지고 오기 때문에 조회 쿼리를 볼 수 없다. 이때 `em.flush()`, `em.clear()`를 하면 DB에 데이터를 반영하고, 영속성 컨텍스트를 초기화한다. 따라서 `em.find()`를 호출하면 영속성 컨텍스트에 데이터가 없으므로 DB에서 데이터를 조회하게 된다.

[Spring Security] 예외 처리하기

jaamong — Fri, 21 Jun 2024 21:39:59 +0900

Notice Spring Boot 3.2.5, Spring Security 6.2.5 기반으로 작성한 글입니다.

아래 포스팅들을 먼저 보면 좋습니다.

Spring Security 6 - Architecture → Security Exception 처리하기
[Spring Security] 토큰 기반 로그인/로그아웃 구현하기

이 글의 목표는 Spring Security에서 토큰 기반 인증을 진행할 때 발생한 예외를 `@RestControllerAdvice`로 처리하는 것입니다.

시큐리티 예외 처리 구현

Spring Security에서 예외 처리는 다음과 같은 아키텍처로 이루어진다.

FilterChain
Spring Security는 `FilterChain`으로 구성되어 있으며, 각 필터는 요청을 처리하거나 다음 필터로 전달한다. 예외가 발생하면 예외 처리 필터가 작동한다.
ExceptionTranslationFilter
해당 필터는 예외를 Spring Security 예외로 변환하고, 적절한 `AuthenticationEntryPoint` 또는 `AccessDeniedHandler`를 호출한다. 이 필터는 이 둘을 주입받아 사용한다.
AuthenticationEntryPoint
`AuthenticationEntryPoint`는 인증되지 않은 요청에 대한 처리를 담당한다. 일반적으로 로그인 페이지로 리디렉션 하거나 401 Unauthorized 응답을 반환한다.
AccessDeniedHandler
`AccessDeniedHandler`는 인가되지 않은 요청(권한 부족)에 대한 처리를 담당한다. 일반적으로 403 Forbidden 응답을 반환한다.

따라서 Spring Security 예외 처리 흐름은 다음과 같다.

요청이 들어온다.
FilterChain에서 예외가 발생한다.
ExceptionTranslationFilter가 예외를 캐치하고, Spring Security 예외로 변환한다.
AuthenticationEntryPoint 또는 AccessDeniedHandler가 호출되어 예외를 처리한다.

위 과정처럼 Spring Security는 요청이 컨트롤러에 도달하기 전에 `FilterChain`에서 예외를 발생시킨다.

`@RestControllerAdvice`는 컨트롤러 계층에서 발생하는 예외를 처리하는데, 시큐리티 예외는 컨트롤러에 도달하기 전에 발생하므로 해당 애노테이션으로 처리할 수 없다.

이를 원하는 대로 처리하려면 예외를 가로채는 `AuthenticationEntryPoint`와 `AccessDeniedHandler`를 사용자 정의하여 구현하면 된다. 본격적으로 구현하기 전에 Security Configuration을 설정하자.

SecurityConfig

...

@Configuration
@RequiredArgsConstructor
public class SecurityConfig {

    ...

    private final CustomAuthenticationEntryPoint authenticationEntryPoint;
    private final CustomAccessDeniedHandler accessDeniedHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

        http
                ...
                .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class)
                .exceptionHandling(e -> e
                        .authenticationEntryPoint(authenticationEntryPoint)
                        .accessDeniedHandler(accessDeniedHandler)
                )
                ...
                ;

        return http.build();
    }
}

Custom AuthenticationEntryPoint

`AuthenticationEntryPoint` 인터페이스는 인증되지 않은 사용자가 인증이 필요한 요청 엔드포인트로 접근하려 할 때 발생하는 401 Unauthorized 예외를 핸들링 할 수 있도록 도와준다.

...

@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {

    private final HandlerExceptionResolver resolver;

    public CustomAuthenticationEntryPoint(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver resolver) {
        this.resolver = resolver;
    }

    @Override
    public void commence(@NonNull HttpServletRequest request,
                         @NonNull HttpServletResponse response,
                         @NonNull AuthenticationException authException) {

        resolver.resolveException(request, response, null, authException);
    }
}

`commence` 메서드는 인증되지 않은 요청이 발생했을 때 호출된다. 여기에서 예외를 처리하는 것이 아닌 `HandlerExceptionResolver`로 넘긴다. 관련 내용은 아래에서 자세하게 다룬다.

Custom AccessDeniedHandler

`AccessDeniedHandler` 인터페이스는 권한이 없는 사용자가 권한이 필요한 요청 엔드포인트로 접근하려 할 때 발생하는 403 Forbidden 예외를 핸들링 할 수 있도록 도와준다.

...

@Component
public class CustomAccessDeniedHandler implements AccessDeniedHandler {

    private final HandlerExceptionResolver resolver;

    public CustomAccessDeniedHandler(@Qualifier("handlerExceptionResolver") HandlerExceptionResolver resolver) {
        this.resolver = resolver;
    }

    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response, AccessDeniedException accessDeniedException) throws IOException, ServletException {

        resolver.resolveException(request, response, null, accessDeniedException);
    }
}

`handle` 메서드는 권한이 없는 요청이 발생했을 때 호출된다. `AccessDeniedHandler`와 마찬가지로 여기에서 예외를 처리하는 것이 아닌 `HandlerExceptionResolver`로 넘긴다.

HandlerExceptionResovler

`HandlerExceptionResolver`는 Spring Security의 영역이 아닌 Spring MVC 영역에 속해있는 컴포넌트이다.

Spring MVC에서 `HandlerExceptionResolver`는 `DispatcherServlet`의 `HandlerExceptionResolver` 체인(예외 처리 체인)에 등록되어 있다. 이 체인은 컨트롤러에서 발생한 예외를 처리하는 역할을 한다.

따라서 각 커스텀 구현한 `AuthenticationEntryPoint`와 `AccessDeniedHandler`에서 `HandlerExceptionResolver`를 호출하여 컨트롤러에서 예외를 처리할 수 있도록 한다.

HandlerExceptionResolver.resolveException(request, response, null, accessDeniedException);

참고로 위 코드처럼 `handler`를 `null`로 반환하면 다음 `ExceptionResolver`를 찾아서 실행한다. 만약 처리할 수 없는 `ExceptionResolver`가 없으면 예외 처리가 안되고, 기존에 발생한 예외를 서블릿 밖으로 던진다.

우리는 `null`을 반환하여 `@RestControllerAdvice`와 `@ExceptionHandler`를 사용하는 클래스에서 예외를 처리하도록 한다.

Custom ExceptionHandler

이곳에서 Spring Security 예외를 처리한다. 보다 깔끔하게 예외를 가공하고 처리하기 위해서 컨트롤러 계층까지 예외를 가져왔다.

`@RestControllerAdvice`를 사용하여 반환하는 값을 Response Body로 설정하고, 이를 클라이언트에게 전달하도록 한다. `@ExceptionHandler`로 각 적절한 예외를 처리할 수 있도록 한다.

...

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler
    public ResponseEntity<ExceptionResponseDto> handleAuthenticationException(AuthenticationException e) {
        ExceptionResponseDto dto = new ExceptionResponseDto(HttpStatus.UNAUTHORIZED.name(), ExceptionCode.INVALID_TOKEN.getMessage());
        HttpStatus httpStatus = HttpStatus.UNAUTHORIZED;
        return ResponseEntity.status(httpStatus).body(dto);
    }

    @ExceptionHandler
    public ResponseEntity<ExceptionResponseDto> handleAccessDeniedException(AccessDeniedException e) {
        ExceptionResponseDto dto = new ExceptionResponseDto(HttpStatus.FORBIDDEN.name(), ExceptionCode.ACCESS_DENIED.getMessage());
        HttpStatus httpStatus = HttpStatus.FORBIDDEN;
        return ResponseEntity.status(httpStatus).body(dto);
    }
		
	...
}

클라이언트에게 예외를 반환할 때 필요한 정보만 담을 수 있도록 별도로 DTO를 생성했다.

참고

[Spring Security] 역할/권한 구현하기

jaamong — Fri, 14 Jun 2024 20:00:58 +0900

Notice Spring Boot 3.2.5, Spring Security 6.2.5 기반으로 작성한 글입니다.

지난 포스팅에서 이어집니다.

[Spring Security]토큰 기반 로그인/로그아웃 구현하기

역할과 권한

사용자의 역할(role)과 권한(permission/authority)을 구현하여 기능 접근에 제약을 둘 수 있다. 만일 권한이 없는 기능에 접근하면 403 Forbidden이 발생한다. 역할 및 권한 구현 시 다음과 같은 것들을 고려해야 한다.

한 역할은 여러 개의 권한을 가질 수 있다.
여러 명의 사용자는 여러 개의 역할을 가질 수 있다. → 다대다 관계

역할을 하나의 Entity로 두어 구현할 수 있지만, 이 경우에 고려할 것이 많아진다.

다대다 관계 매핑 → `@ManyToMany`
- 중간 테이블을 두어 일대다, 다대일로 풀어내기

다대다 관계를 중간 테이블로 해결하는 것이 권장되지만, 이렇게 하면 역할과 관련된 로직이 복잡해진다. 그래서 나는 역할을 Enum 클래스로 구현했다. 마찬가지로 권한도 Enum 클래스로 구현한다.

Enum 클래스로 구현해도 역할은 여러 권한을 가질 수 있고, 사용자도 여러 역할을 갖도록 구현할 수 있다. 여기에서는 사용자가 한 역할만 갖고 있도록 구현했으나, 권한을 역할에 따라 부여하도록 구현했으므로 문제없다. 만일 권한을 세부적으로 정하지 않고 역할로만 기능 접근을 설정한다면 사용자가 여러 역할을 갖도록 하는 것이 좋다.

구현하기

Permission Enum class

어떤 기능을 수행할 수 있는지 나타내는 Permission(권한) 클래스이다.

@Getter
public enum Permission {

    READ("READ_AUTHORITY"),
    CREATE("CREATE_AUTHORITY"),
    UPDATE("UPDATE_AUTHORITY"),
    DELETE("DELETE_AUTHORITY");

    private final String permission;

    Permission(String permission) {
        this.permission = permission;
    }
}

Role Enum class

각 역할 별로 어떤 권한이 있는지 나타낸다.

@Getter
public enum Role {
    ADMIN(Set.of(
            READ,  //Permission enum class
            CREATE,
            UPDATE,
            DELETE
    )),
    MANAGER(Set.of(
            READ,
            CREATE,
            UPDATE
    )),
    USER(Set.of(
            READ
    ));

    private final Set<Permission> permissions;  //Permission enum class

    Role(Set<Permission> permissions) {
        this.permissions = permissions;
    }

    public List<SimpleGrantedAuthority> getAuthorities() {
        List<SimpleGrantedAuthority> authorities = getPermissions()
                .stream()
                .map(permission -> new SimpleGrantedAuthority(permission.getPermission()))
                .collect(Collectors.toList());

        authorities.add(new SimpleGrantedAuthority("ROLE_" + this.name()));

        return authorities;
    }
}

`getAuthorities()`는 역할이 어떤 권한(permission)을 가지고 있는지 반환하는 메서드이다. 이는 `UserDetailsService` 구현체의 `loadUserByUsername`에서 `User` 객체를 생성할 때 사용자가 어떤 권한을 가지고 있는지 반환할 때 사용될 수 있다.

...

@Slf4j
@Service
@RequiredArgsConstructor
public class UserDetailsServiceImpl implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {

        UserEntity user = userRepository.findByUsername(username)
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));

        return new User( //사용자 정보를 담는 객체에 권한도 포함
                user.getUsername(),
                user.getPassword(),
                mapAuthorities(user.getRole()) 
        );
    }

    private Collection<? extends GrantedAuthority> mapAuthorities(Role role) {
        return role.getAuthorities();  //here
    }
}

User Entity class

이렇게 구현된 역할은 `User` 엔티티의 필드가 된다. DB에 저장할 때는 문자열로 저장되도록 설정한다.

...

@Entity
@Table(name = "users")
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
public class UserEntity {

    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "user_id")
    private Long id;

		...

    @Enumerated(EnumType.STRING)
    private Role role;

    @Builder
    public UserEntity(String username, String password, Role role) {
        this.username = username;
        this.password = password;
        this.role = role;
    }

}

참고로 `User` 엔티티가 여러 역할(Role Enum class)를 갖도록 할 때는 아래처럼 하면 되지 않을까?

import jakarta.persistence.*;
import java.util.HashSet;
import java.util.Set;

@Entity
@Table(name = "users")
public class UserEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
	...

    @Enumerated(EnumType.STRING)
    private Set<Role> roles = new HashSet<>();

    // Constructors, getters, and setters
}

다시 돌아와서.. 프로젝트 요구사항에 역할 변경 기능이 없어서 별도로 구현하지 않았으나, 필요하다면 `setter`처럼 구현하면 될 것 같다. (사용자가 여러 개의 역할을 가질 수 있으면 역할 추가, 삭제로 나뉠 수 있다)

이 부분은 프로젝트 마다 다르므로, 프로젝트 요구사항을 바탕으로 설계할 때 적절하게 코드를 작성하자.

이제 `User` 엔티티의 로직과 별개로 이를 수행할 서비스 계층의 비즈니스 로직이 필요하다.

이번에는 해당 역할 및 권한을 가진 사용자만 엔드포인트에 접근할 수 있도록 설정한다.

Spring Security Configuration

@Configuration
@RequiredArgsConstructor
public class SecurityConfig {

    private final String[] PERMIT_ALL_URL = {...};

    ...

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

        http
                ...
                .authorizeHttpRequests(req -> req
                                .requestMatchers(PERMIT_ALL_URL).permitAll()
                                .requestMatchers(HttpMethod.GET, "/api/boards/**").hasAnyAuthority(READ.name())
                                .requestMatchers(HttpMethod.POST, "/api/boards/**").hasAnyAuthority(CREATE.name())
                                .requestMatchers(HttpMethod.PUT, "/api/boards/**").hasAnyAuthority(UPDATE.name())
                                .requestMatchers(HttpMethod.DELETE, "/api/boards/**").hasAnyAuthority(DELETE.name())
                                .anyRequest()
                                .authenticated()
                )
                ...;

        return http.build();
    }
}

`requestMatchers`에 HTTP 메소드와 엔드포인트에 따라 어떤 권한(Authority)이 필요한지 `hasAnyAuthority`를 사용하여 설정한다.

이렇게 security configuration 클래스에서 설정하는 방식 외에 컨트롤러에서 설정할 수 있는 방법도 있다.

Controller

@RestController
@RequestMapping("/api/boards")
@RequiredArgsConstructor
public class BoardController {

    private final BoardService boardService;

    @GetMapping
    @PreAuthorize("hasAuthority('READ_AUTHORITY')")
    public ResponseEntity<..> readAllBoard() {
        // 필요 로직 실행
        return ResponseEntity.ok(..);
    }

    ...
}

모든 게시물을 조회할 수 있는 `GET /api/boards` URL이 매핑된 메서드는 READ_AUTHORITY가 없으면 접근할 수 없도록 `@PreAuthorize`를 사용하여 설정했다. 이렇게 각 메서드 별로 필요한 권한을 지정해 줄 수 있다.

해당 애노테이션을 사용할 때는 `@Configuration`이 적용된 security configuration 클래스에 `@EnabledMethodSecurity` 애노테이션을 추가해야 한다.

@Configuration
@EnableMethodSecurity  //add this
public class SecurityConfig {
	...
}

또한 컨트롤러에 적용했으면 configuration 클래스에 작성한 `requestMatcher` 부분은 제거해도 된다.

@Configuration
@RequiredArgsConstructor
public class SecurityConfig {

    private final String[] PERMIT_ALL_URL = {...};

    ...

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

        http
                ...
                .authorizeHttpRequests(req -> req
                                .requestMatchers(PERMIT_ALL_URL).permitAll()
//                        .requestMatchers(HttpMethod.GET, "/api/boards/**").hasAnyAuthority(READ.name())
//                        .requestMatchers(HttpMethod.POST, "/api/boards/**").hasAnyAuthority(CREATE.name())
//                        .requestMatchers(HttpMethod.PUT, "/api/boards/**").hasAnyAuthority(UPDATE.name())
//                        .requestMatchers(HttpMethod.DELETE, "/api/boards/**").hasAnyAuthority(DELETE.name())
                                .anyRequest()
                                .authenticated()
                )
                ...;

        return http.build();
    }
}

@EnableMethodSecurity

`@Configuration` 클래스에 해당 어노테이션을 달면 Spring이 관리하는 클래스 또는 메소드에 `@PreAuthorize`, `@PostAuthorize`, `@PreFilter`, `@PostFilter` 어노테이션을 달아서 입력 매개변수와 반환값을 포함한 메서드 호출을 승인(authorize)할 수 있다.

예를 들어 특정 컨트롤러에 관리자(ADMIN) 역할을 지닌 사용자만 접근하도록 하고 싶다면 아래와 같이 작성할 수 있다.

@RestController
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {
	...
}

관리자 역할을 지닌 사용자 중에서도 특정 권한을 갖고 있지 않으면 메서드에 접근하지 못하도록 할 수 있다.

@RestController
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {
	
	...
	
	@PostMapping
	@PreAuthorize("hasAuthority('ADMIN_CREATE')")
	public void create(...) {
		...
	}
}

Note request-level(declared in a config class) 인증과의 차이점은 메서드 방식이 좀 더 세밀하게 인증 형식을 설정할 수 있다는 정도다. 애노테이션 인증 관련 자세한 내용은 여기 링크를 참고!

참고

[Spring Security] 토큰 기반 로그인/로그아웃 구현하기

jaamong — Sat, 8 Jun 2024 10:25:14 +0900

Notice Spring Boot 3.2.5, Spring Security 6.2.5 기반으로 작성한 글입니다.

Notice 24.07.06 로그인 구현 부분 `JwtAuthenticationFilter` 잘못된 내용 수정

Spring Security Authentication Architecture

https://memodayoungee.tistory.com/135

Spring Security를 기반으로 보안 관련 기능을 구현하기 위해서는 위의 그림을 이해해야 한다. 아래는 로그인을 예시로 한 Spring Security 인증 과정이다.

1. 사용자가 로그인 정보와 함께 인증을 요청한다.

2. `AuthenticationFilter`가 요청을 가로채어 인증에 사용될 UsernamePasswordAuthenticationToken 객체를 생성한다.

...
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final TokenProvider tokenProvider;
    private final UserDetailsService userDetailsService;
    private final AuthenticationManager authenticationManager;

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {

            /*
	            JWT 유효성 검사 로직
            */
            
            String username = tokenProvider.extractUsername(token);
            UserDetails userDetails = userDetailsService.loadUserByUsername(username);

            // 인증용 토큰 객체 생성
            UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(
                    userDetails,
                    userDetails.getPassword(),
                    userDetails.getAuthorities()
            );
	          ...
           }
       ...
       }

3.`AuthenticationManager`의 구현체인 `ProviderManager`에게 인증 토큰 객체를 전달한다.

Note AuthenticationManager는 Spring Security 필터가 어떻게 인증을 수행해야 하는지 정의한다.

// AuthenticationManager의 구현체인 ProviderManager를 빈으로 등록
// ProviderManager에게 커스텀 AuthenticationProvider를 전달

    @Bean
    public AuthenticationManager authenticationManager(UserDetailsService userDetailsService) {
        JwtAuthenticationProvider provider = new JwtAuthenticationProvider(userDetailsService, passwordEncoder());
        return new ProviderManager(provider);
    }

4. `ProviderManager`는 등록된 `AuthenticationProvider`를 조회하고, 인증을 시도한다.

ProviderManager

각 `AuthenticationProvider`는 특정 타입의 인증을 어떻게 수행하는지 알고 있으므로 어떤 `AuthenticationProvider`는 username/password 검증을 하거나 SAML assertion을 인증할 수도 있다.

public ProviderManager(AuthenticationProvider... providers) {	
	...
	public List<AuthenticationProvider> getProviders() {
        return this.providers;
  }
  ...
}

5, 실제 DB를 통해 사용자의 인증 정보를 가져오는 `UserDetailsService`에게 인증 토큰 객체에 담긴 사용자 정보를 전달한다.

...
public class JwtAuthenticationProvider implements AuthenticationProvider {

    private final UserDetailsService userDetailsService;
    private final PasswordEncoder passwordEncoder;

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        UsernamePasswordAuthenticationToken authToken = (UsernamePasswordAuthenticationToken) authentication;

        String username = authToken.getName();
        if (username == null) {
            throw new UsernameNotFoundException("Invalid username or password");
        }

        // UserDetailsService에게 사용자 정보 전달
        UserDetails userDetails = userDetailsService.loadUserByUsername(username);
       
	      ...
    }

6. 받은 사용자 정보를 이용하여 DB에서 해당 사용자 정보를 찾는다. 찾은 사용자 정보를 바탕으로 `UserDetails` 객체를 생성한다.

...
public class UserDetailsServiceImpl implements UserDetailsService {

    private final UserRepository userRepository;

    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {

       //DB에서 사용자 정보 조회
        UserEntity user = userRepository.findByUsername(username)
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));

        //UserDetails 객체 생성
        return new User(
                user.getUsername(),
                user.getPassword(),
                mapAuthorities(user.getRole())
        );
    }

    //사용자가 가진 권한 반환
    private Collection<? extends GrantedAuthority> mapAuthorities(Role role) {
        return role.getAuthorities();
    }
}

7. `AuthenticationProvider`는 생성한 `UserDetails` 객체를 반환받아, 해당 객체와 인증 토큰 객체에 담긴 사용자 정보를 비교한다.

...
public class JwtAuthenticationProvider implements AuthenticationProvider {

    private final UserDetailsService userDetailsService;
    private final PasswordEncoder passwordEncoder;

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {

        ...        
        // UserDetailsService에게 사용자 정보 전달
        UserDetails userDetails = userDetailsService.loadUserByUsername(username);
        String password = userDetails.getPassword();
       
        // 사용자 정보 비교
        // verifyCredentials: 비밀번호를 검증하는 커스텀 메서드 - 보통 PasswordEncoder#matches 사용
        verifyCredentials(password, (String) authToken.getCredentials());
        ...
    }

8. 인증이 완료되면 권한을 포함하여 사용자 정보를 담은 `Authentication` 객체를 반환한다.

생성할 `Authentication` 객체에는 보안을 위해 비밀번호(credentials)를 담지 않는다.
위 `Authentication` 객체는 `UsernamePasswordAuthenticationToken`으로 구현할 수 있다.

...
public class JwtAuthenticationProvider implements AuthenticationProvider {

    private final UserDetailsService userDetailsService;
    private final PasswordEncoder passwordEncoder;

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {

	      ...        
	      // UserDetailsService에게 사용자 정보 전달
	      ...
       
	      // 사용자 정보 비교
	      ...
				
	      // 인증 토큰 발급 및 반환
	      return new UsernamePasswordAuthenticationToken(
                 username,
                 null,
                 userDetails.getAuthorities()
	      );				
    }

9. 돌아가서 `AuthenticationFilter`에 `Authentication` 객체가 반환된다. [인증 완료]

...
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final TokenProvider tokenProvider;
    private final UserDetailsService userDetailsService;
    private final AuthenticationManager authenticationManager;

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {
						
            ...
						            
            // 인증용 토큰 객체 생성: authenticationToken 
            ...
            
            // 인증 시도 -> 인증 완료: authentication 객체 받음
            Authentication authentication = authenticationManager.authenticate(authenticationToken);
            
            ...
           }
       ...
       }

10. `SecurityContextHolder`의 세션 영역에 있는 `SecurityContext`에 `Authentication` 객체를 저장한다.

Note 사용자 정보를 저장하는 것은 Spring Security가 전통적인 세션-쿠키 기반의 인증 방식을 사용함을 의미한다.

...
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final TokenProvider tokenProvider;
    private final UserDetailsService userDetailsService;
    private final AuthenticationManager authenticationManager;

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {
            ...
						            
            // 인증용 토큰 객체 생성: authenticationToken 
            ...
            
            // 인증 시도 -> 인증 완료: authentication 객체 받음
            Authentication authentication = authenticationManager.authenticate(authenticationToken);
            
            // 인증 객체 설정
            SecurityContextHolder.getContext().setAuthentication(authentication);

            ...
           }
       ...
       }

⇒ 위 모든 과정을 거치고 나서 `Dispatcher Servlet`으로 요청을 넘긴다.

...
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final TokenProvider tokenProvider;
    private final UserDetailsService userDetailsService;
    private final AuthenticationManager authenticationManager;

    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

        String token = getJwtFromRequest(request);
        if (StringUtils.hasText(token)) {
                // 4 ~ 10 과정
        }
        //요청 넘김 (애플리케이션의 나머지 동작 수행)
        filterChain.doFilter(request, response);
    }

모든 필터를 통과하고 애플리케이션에서 할 일을 마친 후 바로 클라이언트로 응답이 가는 것이 아닌, 다시 필터를 통해서 돌아가는 것을 기억합시다.

토큰 기반 로그인(인증) 구현

Spring Security는 기본적으로 `formLogin`을 제공하는데 이는 HTML 폼 기반으로 REST API가 필요할 때는 별도로 구현해야 한다. 또한 JWT를 사용하므로 security configuration 클래스에 관련 설정을 해야 한다.

@Configuration
@RequiredArgsConstructor
public class SecurityConfig {

    ...
   
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

        http
                .csrf(AbstractHttpConfigurer::disable)
                .headers(headers -> headers.frameOptions(HeadersConfigurer.FrameOptionsConfig::sameOrigin))  // H2 웹콘솔 iframe 정상 작동을 위해 같은 Origin에 대해 허용
                .sessionManagement(session -> session.sessionCreationPolicy(STATELESS)) //here
                ...
                ;

        return http.build();
    }
}

현재 토큰 기반의 인증을 구현하므로 사용자의 로그인 요청이 성공하면 Access Token과 Refresh Token을 발급하도록 구현한다. 로그인 요청 시에는 토큰 인증이 아닌 로그인 요청 정보(Response Body)만 검증하도록 한다.

따라서 로그인 요청인 경우에는 Header에 토큰이 없으므로 바로 다음 필터로 넘어가게 된다.

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    ...
    
    @Override
    protected void doFilterInternal(@NonNull HttpServletRequest request,
                                    @NonNull HttpServletResponse response,
                                    @NonNull FilterChain filterChain) throws ServletException, IOException {

				
                // JWT 검사 및 인증 객체 설정
                String token = getJwtFromRequest(request);
                if (StringUtils.hasText(token)) {
                	//Header에 JWT가 있는 요청들은 이 부분 실행
                	...
                }
                //Header에 JWT가 없는 요청들은 바로 doFilter() 실행. Ex) 회원가입 등...
                filterChain.doFilter(request, response);		
        }
}

토큰 인증 등의 과정을 진행하지 않고 바로 `FilterChain.doFilter(request, response)`를 호출한다.

Note 참고로 spring security configuration에서 해당 URI를 `permitAll()` 처리해도 이는 `filter`를 거칩니다. 아예 해당 URI를 무시하는 방법도 있으나 이는 보안 측면에서 권장되지 않는 방법입니다.

이제 로그인 요청을 처리하는 컨트롤러 코드를 구현한다.

...

@Slf4j
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthenticationController {

    private final AuthenticationService authService;

    @PostMapping("/sign-in")
    public ResponseEntity<AuthenticationRespDto> authenticate(@RequestBody AuthenticationReqDto dto) {

        log.info("[authenticate] login request: {}", dto);
        authService.isValidCredentials(dto); //here
				
				...
    }
}

로그인 정보와 함께 `/api/auth/sign-in`으로 요청이 들어오면 `AuthService#isValidCredentials` 메서드에서 로그인 정보를 검증한다.

@Service
@Transactional
@RequiredArgsConstructor
public class AuthenticationService {

    private final PasswordEncoder passwordEncoder;
    private final UserRepository userRepository;
    ...
    
    public AuthenticationRespDto authenticate(AuthenticationReqDto dto) {

        //jwt, refresh token 발급
        UserDetails userDetails = userDetailsService.loadUserByUsername(dto.username());
        String jwt = tokenProvider.generateToken(userDetails);
        String refreshToken = tokenProvider.generateRefreshToken(userDetails);

        //이전 토큰 무효화 및 새 토큰 저장
        UserEntity user = userRepository.findByUsername(dto.username())
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));
        revokeUserAllTokens(user);
        saveUserToken(user, jwt);

        return new AuthenticationRespDto(jwt, refreshToken);
    }
			
    public void isValidCredentials(AuthenticationReqDto dto) {
        UserEntity user = userRepository.findByUsername(dto.username())
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));

        if (user == null || !passwordEncoder.matches(dto.password(), user.getPassword())) {
            throw new BadCredentialsException("Invalid username or password");
        }
    }
    
    ...
}

`username`이 DB에 있는지 확인한다. 없으면 `UsernameNotFoundException`을 던지고, 있으면 해당 정보를 가진 객체를 꺼낸다.
DB에서 꺼낸 객체의 `password`와 사용자가 입력한 `password`를 비교한다. 일치하지 않으면 `BadCredentialsException`을 던진다.

검증이 성공적으로 완료되면 다시 컨트롤러로 돌아간다.

...

@Slf4j
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthenticationController {

    private final AuthenticationService authService;

    @PostMapping("/sign-in")
    public ResponseEntity<AuthenticationRespDto> authenticate(@RequestBody AuthenticationReqDto dto) {

        log.info("[authenticate] login request: {}", dto);
        authService.isValidCredentials(dto);
        
        AuthenticationRespDto response = authService.authenticate(dto); //here
        log.info("[authenticate] login response: {}", response);
				
				...
    }
}

`AuthService#authenticate`를 호출하여 JWT 토큰을 생성한다.

@Service
@Transactional
@RequiredArgsConstructor
public class AuthenticationService {

    private final UserDetailsService userDetailsService;
    private final TokenProvider tokenProvider;
    private final UserRepository userRepository;
    private final TokenRepository tokenRepository;
    ...
    
    public AuthenticationRespDto authenticate(AuthenticationReqDto dto) {

        //jwt, refresh token 발급
        UserDetails userDetails = userDetailsService.loadUserByUsername(dto.username());
        String jwt = tokenProvider.generateToken(userDetails);
        String refreshToken = tokenProvider.generateRefreshToken(userDetails);

        //이전 토큰 무효화 및 새 토큰 저장
        UserEntity user = userRepository.findByUsername(dto.username())
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));
        revokeUserAllTokens(user);
        saveUserToken(user, jwt);

        return new AuthenticationRespDto(jwt, refreshToken);
    }	
    
    ...
}

`UserDetailsService#loadUserByUsername`를 이용하여 사용자 정보를 담는 객체인 `UserDetails`를 생성한다.
해당 객체를 `TokenProvider#generateToken`으로 넘겨 사용자 정보를 바탕으로 Access Token을 생성한다.
그다음에 Refresh Token을 생성하는 `TokenProvider#generateRefreshToken`을 호출한다.

토큰 생성 과정에서 예외 발생 없이 잘 넘어가면 사용자가 이전에 발급받은 모든 토큰을 무효화(invalide) 처리한다.

    private void revokeUserAllTokens(UserEntity user) {
        List<Token> userTokens = tokenRepository.findAllValidTokenByUser(user.getId());

        if (userTokens.isEmpty()) return;

        // 사용자 모든 토큰 만료시키기
        userTokens.forEach(token -> {
            token.configureRevoked(true);
            token.configureExpired(true);
        });

        tokenRepository.saveAll(userTokens);
    }

이제 새롭게 발급한 토큰을 저장한다.

    private void saveUserToken(UserEntity user, String jwt) {
        Token token = Token.builder()
                .user(user)
                .token(jwt)
                .expired(false)
                .revoked(false)
                .build();
        tokenRepository.save(token);
    }

모든 과정이 성공적으로 완료되면 생성된 Access Token, Refresh Token을 DTO 객체에 담아 반환한다.

다시 컨트롤러로 돌아온다.

...

@Slf4j
@RestController
@RequestMapping("/api/auth")
@RequiredArgsConstructor
public class AuthenticationController {

    private final AuthenticationService authService;

    @PostMapping("/sign-in")
    public ResponseEntity<AuthenticationRespDto> authenticate(@RequestBody AuthenticationReqDto dto) {

        log.info("[authenticate] login request: {}", dto);
        authService.isValidCredentials(dto);
        
        AuthenticationRespDto response = authService.authenticate(dto); //here
        log.info("[authenticate] login response: {}", response);
				
        return ResponseEntity.ok(response); //here
    }
}

반환받은 DTO를 `ResponseEntity`에 담아서 사용자에게 반환한다.

토큰 기반 로그아웃 구현

Spring Security에 JWT 기반 로그아웃을 위한 내장된 구현은 별도로 없다. JWT의 stateless 특성으로 인하여 서버는 사용자의 세션을 저장하거나 추적하지 않기 때문이다.

따라서 클라이언트가 토큰 관리와 로그아웃 과정 초기화를 담당하게 된다. 프론트엔트의 경우 사용자는 토큰을 로컬 스토리지에서 제거하거나 토큰이 만료되도록 만료 날짜를 변경 또는 설정하면 된다. 또는 백엔드에서 이러한 토큰에 관한 보안이나 무효화하는 메커니즘을 구현할 수도 있다.

여기에서는 로그아웃을 구현할 때 Spring Security에게 로그아웃을 위한 엔드포인트를 제공하고, Spring은 개발자에게 로그아웃 핸들러를 제공한다.

우선 Security Configuration에서 로그아웃 설정을 한다.

...

@Configuration
@RequiredArgsConstructor
@EnableMethodSecurity
public class SecurityConfig {

		...

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {

        http
                ...
                .logout(logout -> logout.logoutUrl("/api/auth/sign-out")
                        .addLogoutHandler(logoutHandler)
                        .logoutSuccessHandler((request, response, authentication) -> SecurityContextHolder.clearContext())
                );

        return http.build();
    }
}

로그아웃 요청을 받을 URL을 지정한다.

로그아웃을 처리할 `LogoutHandler`를 등록한다. 이 핸들러는 `LogoutHandler` 인터페이스를 구현한 구현체이다.

...

@Service
@RequiredArgsConstructor
public class LogoutHandlerImpl implements LogoutHandler {

    private final TokenRepository tokenRepository;

    @Override
    public void logout(HttpServletRequest request, HttpServletResponse response, Authentication authentication) {
        String token = getJwtFromRequest(request);

        Token storedToken = tokenRepository.findByToken(token)
                .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "존재하지 않는 토큰(JWT)입니다."));

        //토큰 무효화하기
        storedToken.configureExpired(true);
        storedToken.configureRevoked(true);

        tokenRepository.save(storedToken);
    }

    private String getJwtFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");

        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

요청에서 토큰을 꺼낸다.
해당 토큰이 DB에 있는지 확인한다.
- 토큰이 없는 경우 `404 NOT FOUND` 에러가 발생한다.
DB에 토큰이 있으면 토큰을 무효화 설정한다.
설정 후에 해당 변경을 저장한다.

로그아웃이 성공하면 호출되는 `logoutSuccessHandler`를 설정한다.

여기의 로그아웃 구현은 로그아웃 핸들러 외에 특별히 설정할 것이 없다. 관련하여 자세한 내용은 아래 링크를 참고!

Handling Logouts :: Spring Security

If you are using Java configuration, you can add clean up actions of your own by calling the addLogoutHandler method in the logout DSL, like so: Custom Logout Handler CookieClearingLogoutHandler cookies = new CookieClearingLogoutHandler("our-custom-cookie"

docs.spring.io

번외. JWT Authentication

기간 내에 구현하려고 하다 보니 공식 문서를 꼼꼼히는 뒤늦게 보게 됐는데, 이런 부분이 있더라... 나중에 참고하기 위해 남겨두기..

OAuth 2.0 Resource Server JWT :: Spring Security

Most Resource Server support is collected into spring-security-oauth2-resource-server. However, the support for decoding and verifying JWTs is in spring-security-oauth2-jose, meaning that both are necessary in order to have a working resource server that s

docs.spring.io

참고

Spring Security 6 - Architecture

jaamong — Fri, 7 Jun 2024 20:00:58 +0900

Spring Security 6 - Architecture 공식 문서를 번역했습니다. 필요에 의해 설명을 추가한 부분도 있습니다.

Architecture :: Spring Security

The Security Filters are inserted into the FilterChainProxy with the SecurityFilterChain API. Those filters can be used for a number of different purposes, like authentication, authorization, exploit protection, and more. The filters are executed in a spec

docs.spring.io

Spring Security Architecture

Spring Security는 인증, 검증, 권한 부여를 편리하게 할 수 있도록 도와주는 Spring Framework의 라이브러리이다.

Filter

Spring Security는 Spring MVC의 `Dispatcher Servlet` 보다 앞인 `Servlet Container` 내부에 존재하는 `Filter`에서 시작한다.

Servlet Container를 보면 Filter가 Dispatcher Servlet 보다 앞에 위치하고 있다.

따라서 `Filter`의 역할을 먼저 찾아보는 것이 이해에 도움 된다. 아래 그림은 단일 HTTP 요청에 대한 핸들러의 일반적인 계층을 보여준다.

FilterChain

클라이언트가 애플리케이션으로 요청을 보내면 컨테이너는 요청 URI 경로를 따라 `HttpSevletRequest`를 처리해야 하는 필터 인스턴스와 서블릿을 포함하는 `FtilerChain`을 생성한다.

하나 이상의 `Filter`를 사용하여 다음을 할 수 있다.

다운 스트림 필터 인스턴스(Downstream Filter Instance) 또는 서블릿이 호출되지 않도록 한다. 이 경우 필터는 일반적으로 `HttpServletResponse`를 작성한다.
다운 스트림 필터 인스턴스 및 서블릿에서 사용하는 `HttpServletRequest` 또는 `HttpServletResponse`를 수정한다.

Note 자신보다 먼저 호출되는 필터를 `Upstream Filter`, 나중에 호출되는 필터를 `Downstream Filter`라고 한다.

여러 개의 필터가 연결되어 이루어진 `FilterChain`은 서블릿 컨테이너 내부에서 클라이언트의 요청이 서블릿에 도달하기 전에 인가 처리, 권한 부여, 요청 로깅, 예외 처리 등과 같은 작업을 처리한다.

아래 코드는 `FilterChain` 예제이다. 모든 필터를 통과하고 애플리케이션에서 할 일을 마친 후 바로 클라이언트로 응답이 가는 것이 아닌, 다시 필터를 통해서 돌아가는 것을 알 수 있다.

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    // do something before the rest of the application
    chain.doFilter(request, response); // invoke the rest of the application
    // do something after the rest of the application
}

필터는 다운 스트림 필터 인스턴스와 서블릿에만 영향을 미치므로 각 필터가 호출되는 순서는 매우 중요하다.

DelegatingFilterProxy

Spring은 서블릿 컨테이너 생명 주기와 Spring의 `ApplicationContext` 사이를 연결해 주는 `DelegatingFilterProxy`라는 필터 구현체를 제공한다. 일반적인 필터들은 Spring에서 정의된 `Bean`을 인지할 수 없지만, `DelegatingFilterProxy`는 필터이면서 `Bean`에게 작업을 위임할 수 있다.

아래 코드는 `DelegatingFilterProxy`의 의사 코드(pseudo code)이다.

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    Filter delegate = getFilterBean(someBeanName);
    delegate.doFilter(request, response);
}

위 코드의 첫 줄은 `Bean`으로 등록된 필터를 Lazy하게 가져오는 작업을 수행한다. `DelegatingFilterProxy`는 필터 빈 인스턴스 조회를 지연시킬 수 있는 장점을 갖고 있다.

필터 인스턴스는 컨테이너가 시작되기 전에 등록되어야 한다. 그러나 Spring은 일반적으로 `ContextLoadListener`를 사용하여 `Spring Bean`을 로드하는데, 이는 필터 인스턴스를 등록한 후에 수행되므로 필터 빈 인스턴스 조회를 지연시킬 수 있다.

FilterChainProxy

SpringSecurity가 제공하는 `FilterChainProxy`는 `SecurityFilterChain`을 통해 많은 필터 인스턴스에 위임할 수 있게 하는 필터이다. 또한 `FilterChainProxy`는 `Bean`이기 때문에 일반적으로 `DelegatingFilterProxy`로 감싸지게 된다.

FilterChainProxy

SecurityFilterChain

`FilterChainProxy`는 현재 요청에 대해 호출되어야 하는 Spring Security 필터 인스턴스를 결정하기 위해 `SecurityFilterChain`을 사용한다.

SecurityFilterChain

`SecurityFilterChain` 내부의 `Security Filter`들은 일반적으로 `Bean`이지만, `DelegatingFilterProxy`가 아닌 `FilterChainProxy`에 등록된다. `FilterChainProxy`는 서블릿 컨테이너 또는 `DelegatingFilterProxh`에 직접 등록하는 것보다 여러 가지 이점을 제공한다.

Spring Security가 서블릿 기반으로 제공하는 모든 기능의 시작점이므로, 트러블 슈팅 시 `FilterChainProxy`에 디버그 포인트를 추가하기 좋다.
`FilterChainProxy`는 Spring Security 사용의 핵심이다. 이는 `SecurityContext`를 초기화하여 메모리 누수를 피하거나, `HttpFirewall`을 적용하여 특정 유형의 공격으로부터 애플리케이션을 보호하도록 한다.
`SecurityFilterChain`이 언제 호출되어야 하는지 보다 유연하게 결정할 수 있도록 한다. 서블릿 컨테이너 안에서 필터 인스턴스는 URL만을 기반으로 호출되지만, `FilterChainProxy`는 `RequestMatcher` 인터페이스를 사용하여 `HttpServletRequest`의 모든 것을 기반으로 호출을 결정할 수 있다.

다중 SecurityFilterChain

`FilterChainProxy`는 멤버 변수로 `List<SecurityFliterChain> filterChains`를 가직 ㅗ있어 여러 개의 `SecurityFilterChain`을 모두 저장할 수 있으며, 현재 요청에 따라 어떤 `SecurityFilterChain`을 사용할지 결정한다(위 FilterChainProxy의 이점 3번).

아래 그림을 보면, `SecurityFilterChain 0`은 총 3개의 필터로, `SecurityFilterChain n`은 4 개의 필터로 구성되어 있는 것을 확인할 수 있다. 이를 통해 각 `SecurityFilterChain`은 유니크하고 독립적으로 구성될 수 있음을 알 수 있다. `SecurityFilter`를 통해 검사할 필요가 없는 요청에 대해서는 0개의 필터로 구성된 `SecurityFilterChain`을 적용할 수 있다.

Multiple SecurityFilterChain

아래 코드는 실제 Spring Security의 `FilterChainProxy` 코드 중 일부이다.

private List<Filter> getFilters(HttpServletRequest request) {
        int count = 0;
        Iterator var3 = this.filterChains.iterator();

        SecurityFilterChain chain;
        do {
            if (!var3.hasNext()) {
                return null;
            }

            chain = (SecurityFilterChain)var3.next();
            if (logger.isTraceEnabled()) {
                ++count;
                logger.trace(LogMessage.format("Trying to match request against %s (%d/%d)", chain, count, this.filterChains.size()));
            }
        } while(!chain.matches(request));

        return chain.getFilters();
    }

`while`문의 조건을 보면, 요청과 일치하는 SecurityFilterChain의 차례가 되면 반복문이 종료되는 것을 확인할 수 있다. 이를 통해 가장 먼저 매칭되는 단 하나의 `SecurityFilterChain`만이 호출됨을 알 수 있다. 위에서 언급한 것처럼 순서가 매우 중요하다는 의미이다.

위 그림을 다시 보면, `SecurityFilterChain 0`는 `/api/**`에 대해, `SecurityFilterChain n`은 `/**`에 매칭되도록 설정되어 있다. 예를 들어, `/api/message/` URL이 요청되면 `SecurityFilterChain 0`이 가장 처음으로 매칭되므로 `SecurityFilterChain 0`만이 호출되어 이를 통한 검증이 이루어지게 된다.

Security Filters

`Security Filter`는 `SecurityFilterChain API`를 사용하여 `FilterChainProxy`에 삽입된다 `Security Filter`는 다양한 목적(인증, 인가, 악용 방지 등)으로 사용될 수 있으며, 적시에 호출되도록 특정 순서로 실행된다.

예를 들어, 인증(Authentication)을 수행하는 필터는 권한 부여(Authorization)를 수행하는 필터보다 호출되어야 한다. 두 필터가 반대의 순서로 호출되면 정상적인 작동을 보장할 수 없다.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(Customizer.withDefaults()) //CsrfFilter
            .authorizeHttpRequests(authorize -> authorize //AuthorizationFilter
                .anyRequest().authenticated()
            )
            .httpBasic(Customizer.withDefaults()) //BasicAuthenticationFilter
            .formLogin(Customizer.withDefaults()); //UsernamePasswordAuthenticationFilter
        return http.build();
    }

}

위와 같이 설정할 경우, 아래와 같은 순서대로 필터가 실행될 것이다.

CSRF 공격에 대항하여 `CsrfFilter`가 호출된다.
요청을 인증하기 위해 인증 필터(authentication filters)가 호출된다.
요청을 인가하기 위해 `AuthorizationFilter`가 호출된다.

Security Filter 출력하기

추가한 필터가 `Security Filter` 목록에 있는지 확인하고 싶을 때와 같이, 특정 요청에 대해 호출되는 `Security Filter` 목록 확인이 필요할 때가 있다.

필터 목록은 `INFO` 레벨 수준에서 출력되므로, 다음과 같은 결과를 콘솔창에서 볼 수 있다.

2023-06-14T08:55:22.321-03:00  INFO 76975 --- [           main] o.s.s.web.DefaultSecurityFilterChain     : Will secure any request with [
org.springframework.security.web.session.DisableEncodeUrlFilter@404db674,
org.springframework.security.web.context.request.async.WebAsyncManagerIntegrationFilter@50f097b5,
org.springframework.security.web.context.SecurityContextHolderFilter@6fc6deb7,
org.springframework.security.web.header.HeaderWriterFilter@6f76c2cc,
org.springframework.security.web.csrf.CsrfFilter@c29fe36,
org.springframework.security.web.authentication.logout.LogoutFilter@ef60710,
org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter@7c2dfa2,
org.springframework.security.web.authentication.ui.DefaultLoginPageGeneratingFilter@4397a639,
org.springframework.security.web.authentication.ui.DefaultLogoutPageGeneratingFilter@7add838c,
org.springframework.security.web.authentication.www.BasicAuthenticationFilter@5cc9d3d0,
org.springframework.security.web.savedrequest.RequestCacheAwareFilter@7da39774,
org.springframework.security.web.servletapi.SecurityContextHolderAwareRequestFilter@32b0876c,
org.springframework.security.web.authentication.AnonymousAuthenticationFilter@3662bdff,
org.springframework.security.web.access.ExceptionTranslationFilter@77681ce4,
org.springframework.security.web.access.intercept.AuthorizationFilter@169268a7]

뿐만 아니라 각 요청에 대해 각 필터의 호출을 출력하도록 애플리케이션을 구성할 수도 있다. 이렇게 하면 추가한 필터가 특정 요청에 대해 호출되는지 확인하거나, 예외가 발생하는 위치를 찾는 데 유용하다. 이를 위해 보안 이벤트(security event)를 기록하도록 애플리케이션을 구성할 수 있다.

Filter Chain에 사용자 정의 필터 추가하기

대부분 기본 필터로도 충분하지만, 커스텀/사용자 정의 필터가 필요할 수도 있다. 예를 들어 `tenant id header`를 가져오는 필터를 추가하여 현재 사용자가 해당 `tenant`에 액세스 할 수 있는지 확인하려고 한다고 가정해 보자. 이전 설명에서 이미 필터를 추가할 위치에 대한 단서를 제공했는데, 현재 사용자를 알아야 하므로 인증 필터(authentication filter) 다음에 해당 기능을 수행하는 필터를 추가해야 한다.

import java.io.IOException;

import jakarta.servlet.Filter;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

import org.springframework.security.access.AccessDeniedException;

public class TenantFilter implements Filter {

    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain filterChain) throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;

        String tenantId = request.getHeader("X-Tenant-Id"); (1)
        boolean hasAccess = isUserAllowed(tenantId); (2)
        if (hasAccess) {
            filterChain.doFilter(request, response); (3)
            return;
        }
        throw new AccessDeniedException("Access denied"); (4)
    }

}

`request header`에서 `tenant id`를 가져온다.
현재 사용자가 가져온 `tenant id`에 대해 접근 권한이 있는지 확인한다.
권한이 있으면, `chain`에 남은 필터들을 호출한다.
권한이 없으면, `AccessDeniedException`을 던진다.

Note `Filter`를 구현하는 대신 `OncePerRequestFilter`를 구현해도 된다. 이는 요청 당 한 번만 호출되는 필터의 베이스 클래스이며, `HttpServletRequest` 및 `HttpServletResponse` 매개 변수와 함께 `doFilterInternal` 메서드를 제공한다.

이제 위 필터를 `security filter chain`에 등록해야 한다.

`HttpSecurity#addFilterBefore`를 사용하여 사용자 정의 필터인 `TenantFilter`를 `AuthorizationFilter` 앞에 등록한다.

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        // ...
        .addFilterBefore(new TenantFilter(), AuthorizationFilter.class);
    return http.build();
}

`TenantFilter`가 인증 필터 뒤에 호출되도록 `AuthorizationFilter` 앞에 해당 필터를 등록했다.

`HttpSecurity#addFilterAfter`를 사용하여 특정 필터 뒤에 호출되도록 하거나 `HttpSecurity#addFilterAt`을 사용하여 `filter chain`의 특정 필터 위치에 필터를 등록할 수 있다.

`Filter`를 구현한 사용자 정의 필터를 `@Bean` 또는 `@Component`을 사용하여 `Spring Bean`으로 등록할 때 주의해야 할 점이 있다.

Spring Boot는 해당 커스텀 필터를 자동으로 임베디드 컨테이너에 등록한다. 이로 인해 필터가 다른 순서로 두 번 호출되게 할 수도 있다; 컨테이너에 의해 한 번, Spring Security에 의해 한 번.

하지만 해당 커스텀 필터가 의존관계 주입이 필요한 경우에는 `Spring Bean`으로 명시적으로 선언해야 한다. 이는 위에서 언급한 `Security Filter`와 `Spring Bean` 사이의 초기화 순서와 연관되어 있다.

Spring Security Filter 초기화
`Filter`나 `OncePerRequestFilter`를 구현한 커스텀 필터는 메인 애플리케이션 컨텍스트가 완전히 로드되고 모든 `bean`이 인스턴스화되기도 전에 애플리케이션 시작 프로세스에서 매우 일찍 초기화되고 등록된다.
Spring Bean 초기화
커스텀 필터가 필요로 하는 의존관계를 포함한 `Spring Bean`은 `security filter`가 등록된 후 시작 프로세스 후반에 초기화되고 인스턴스화된다.
의존관계 주입
커스텀 필터가 의존관계 주입을 필요로 하면 Spring은 의존관계 주입 없이는 필터를 자동으로 인스턴스화하고 등록할 수 없다. 이는 Spring Security가 해당 필터를 초기화하고 등록할 때 아직 의존 관계는 사용할 수 없기 때문이다.
Spring Bean으로 등록하기
커스텀 필터를 `Spring Bean`으로 명시적으로 등록하면, Spring은 커스텀 필터 `bean`의 생명 주기를 관리하고 필터의 의존 관계를 올바르게 해결할 수 있게 된다. 메인 애플리케이션 컨텍스트가 완전히 로드될 때 Spring은 커스텀 필터 `bean`을 인스턴스화하고 필요한 의존 관계를 주입할 수 있다.

의존 관계 주입을 활용하고 중복 호출을 피해야 하는 경우, `FilterRegistrationBean`을 `bean`으로 선언하고 해당 `enabled` 속성을 `false`로 설정하여 컨테이너에 등록하지 않도록 Spring Boot에게 지시할 수 있다.

@Bean
public FilterRegistrationBean<TenantFilter> tenantFilterRegistration(TenantFilter filter) {
    FilterRegistrationBean<TenantFilter> registration = new FilterRegistrationBean<>(filter);
    registration.setEnabled(false);
    return registration;
}

`OncePerRequestFilter`와 중복 호출에 관련된 개인적인 고찰
`OncePerRequestFilter`를 구현한 커스텀 필터의 경우에는 `FilterRegistrationBean` 빈을 선언하고 `enabled` 속성을 `false`로 설정할 필요는 없는 것 같다. `OncePerRequestFilter`는 한 요청 당 한 번만 호출되도록 Spring Security에서 내부적으로 처리하기 때문이다.
실제로 해당 커스텀 필터가 호출될 때 로그를 찍어보면 한 번만 출력되는 것을 확인할 수 있다.

Security Exception 처리하기

`ExceptionTranslationFilter`는 `AccessDeniedException`과 `AuthenticationException`을 HTTP Response로 변환할 수 있다. 해당 예외 필터는 `security filter` 중 하나로 `FilterChainProxy`에 삽입된다.

Relationship of `ExceptionTranslationFilter` to other components

`ExceptionTranslationFilter`가 `FilterChain.doFilter(request, response)`를 호출한다.
인증되지 않은 사용자 거나 `AuthenticationException`이 발생한 경우, 인증 프로세스를 시작한다.
- SecurityContextHolder를 비운다.
- 인증이 성공하면 원래의 요청을 다시 실행할 수 있도록 `HttpServletRequest`를 저장해둔다.
- `AuthenticationEntryPoint`는 클라이언트로부터 자격 증명(request credentails)을 요청하는 데 사용된다. 예를 들어 로그인 페이지로 리디렉션 되거나 `WWW-Authenticate` 헤더를 보낼 수도 있다.
2번이 아닌 `AccessDeniedException`인 경우, 접근이 거부된다(Access Denied). 거부된 접근을 처리하기 위해 `AccessDeniedHandler`가 호출된다.

Note 애플리케이션이 `AccessDeniedException` 또는 `AuthenticationException`을 던지지 않으면, `ExceptionTranslationFilter`는 아무것도 하지 않는다.

아래는 `ExceptionTranslationFilter` 의사코드이다.

try {
    filterChain.doFilter(request, response); //(1)
} catch (AccessDeniedException | AuthenticationException ex) {
    if (!authenticated || ex instanceof AuthenticationException) {
        startAuthentication(); //(2)
    } else {
        accessDenied(); //(3)
    }
}

Filter에서 설명한 것처럼 `FilterChain.doFilter(request, response)`는 나머지 애플리케이션을 호출하는 것과 동일하다. 이는 애플리케이션의 다른 부분(FilterSecurityIntercepter 또는 method security)이 `AuthenticationException` 또는 `AccessDeniedException`을 던지는 경우, 여기서 `catch`되어 처리될 수 있음을 의미한다.
사용자가 인증되지 않았거나 `AuthenticationException`이 발생한 경우, 인증 프로세스를 시작한다.
2번이 아니라면, 접근이 거부된다(Access Denied).

인증 간 Request 저장하기

어떤 요청이 인증되지 않았는데 인증이 필요한 자원에 관한 것일 때 인증 성공 후 다리 요청하기 위해 인증된 자원에 대한 요청을 저장해두어야 한다. Spring Security에서는 `RequestCahe` 구현체를 사용한 `HttpServletRequest`를 저장하여 이 작업을 수행한다.

RequestCache

`HttpServletRequest`는`RequestCache`에 저장된다. 사용자가 인증을 성공할 때 `RequestCache`는 원래의 요청을 다시 실행하는 데 사용된다. `RequestCacheAwareFilter`는 사용자가 인증한 후 `RequestCache`를 사용하여 저장된 `HttpServletRequest`를 가져오고, `ExceptionTranslationFilter`는 사용자를 로그인 엔드포인트로 리디렉션 하기 전에 `AuthenticationException`을 감지한 후 `RequestCache`를 사용하여 `HttpServletRequest`를 저장한다.

기본적으로 하나의 `HttpSessionRequestCache`가 사용된다. 아래의 코드는 `continue`라는 매개변수가 있는 경우, 저장된 요청에 대해 `HttpSession`을 확인하는 데 사용되는 `RequestCache` 구현체를 사용자 정의(customize)하는 방법을 보여 준다.

@Bean
DefaultSecurityFilterChain springSecurity(HttpSecurity http) throws Exception {
	HttpSessionRequestCache requestCache = new HttpSessionRequestCache();
	requestCache.setMatchingRequestParameterName("continue");
	http
		// ...
		.requestCache((cache) -> cache
			.requestCache(requestCache)
		);
	return http.build();
}

요청이 저장되지 않도록 방지하기

세션에 인증되지 않은 요청을 저장하지 않고, 대신 브라우저나 DB로 옮겨 저장하고 싶을 수도 있다. 또는 로그인하지 않은 사용자가 방문하려는 페이지 대신 홈페이지로 리디렉션 하는 것을 원하면 이 기능을 사용하지 않을 수도 있다.

이 경우에는 `NullRequestCache` 구현체를 사용하면 된다.

@Bean
SecurityFilterChain springSecurity(HttpSecurity http) throws Exception {
    RequestCache nullRequestCache = new NullRequestCache();
    http
        // ...
        .requestCache((cache) -> cache
            .requestCache(nullRequestCache)
        );
    return http.build();
}

RequestCacheAwareFilter

`RequestCacheAwareFilter`는 `RequestCache`를 사용하여 원래의 요청을 다시 실행한다.

Logging

Spring Security는 모든 보안 관련 이벤트에 대해 `DEBUG` 및 `TRACE` 레벨에서 포괄적인 로깅을 제공한다. Spring Security는 요청이 거부된 자세한 이유를 response body에 담지 않기 때문에 이는 애플리케이션을 디버깅할 때 유용하다. 401/403 에러가 발생하면 무슨 일이 일어나고 있는지 이해에 도움이 되는 로그를 발견할 수도 있다.

logging:
  level:
    org:
      springframework:
        security: TRACE

[TIL / SQL] relation, type, constraint, FK (MySQL)

jaamong — Sat, 11 May 2024 17:05:47 +0900

이 글은 아래 강의를 바탕으로 작성했습니다.

[지금 무료] 시니어 백엔드 개발자가 알려주는 데이터베이스 개론 & SQL | 쉬운코드 - 인프런

쉬운코드 | 백엔드 개발자라면 꼭 알아야 할 데이터베이스와 SQL! 이해하기 쉽게 설명하는 것을 최우선으로 합니다., 데이터베이스 + SQL, 누구나 쉽게! 왕초보도 이해하기 쉬운 DB + SQL 기본기!

www.inflearn.com

relation in SQL

Relational Data Model의 relation은 SQL에서 table을 의미한다(완전히 구분 짓지는 않음). 그리고 SQL에서 relation이란 `multiset of tuples`로 중복된 tuple을 허용한다는 의미이다.

`multiset`은 중복을 하용하지 않는 `set`과 달리 중복을 허용하므로 각 tuple이 중복될 수 있다.

Type in SQL(MySQL)

char vs varchar

MySQL에서는 휴대전화 번호와 같이 길이가 일정한 경우에는 `char`, 그렇지 않은 경우에는 `varchar`를 쓰는 것이 좋다. `char`가 `varchar`보다 속도가 빠르기 때문에 무조건 `varchar`를 쓰는 것보다 위와 같은 경우를 따져보고 선택하자.

byte-string

해당 타입은 문자열이 아닌 byte string을 저장하는데 쓰인다. MySQL에는 `BINARY`, `VARBINARY`, `BLOB` 타입이 해당된다. 이는 암호화할 때의 키를 저장할 때 쓰인다.

Constraint

UNIQUE

`unique`는 중복을 허용하지 않는다.

`NULL` 중복 허용은 DB마다 다르다. MySQL은 `NULL` 중복을 허용한다.
보통 `NULL`을 허용하지 않는 `NOT NULL`과 같이 사용한다.

CHECK

attribute의 값을 제한하고 싶을 때 사용한다.
Ex. CHECK (age > 20) → 20살 이하는 저장하지 않는다.
둘 이상의 attribute로 구성될 때는 attribute의 바로 옆이 아닌, 맨 아래에 기입한다.

constraint 이름 명시하기

이름을 붙이면 어떤 constraint를 위반했는지 쉽게 파악할 수 있다.
constraint를 삭제하고 싶을 때 해당 이름으로 삭제할 수 있다.

Example SQL

create table TEST (
	age INT CONSTRAINT age_over_20 CHECK(age>20)
);

CHECK(age>20): 나이가 20살이 넘도록 constraint를 걸어 놓음
- 이에 대해 이름 붙이기: `CONSTRAINT {constraint 이름}`
이름을 붙인 상태로 constraint를 위반하면 다음과 같이 에러가 난다 → `Check constraint 'age_over_20' is violated.`

FOREIGN KEY 선언 방법

MySQL

create table EMPLOYEE ( 
	... 
	dept_id INT, FOREIGN KEY (dept_id) references DEPARTMENT(id) 
            on delete reference_option 
            on update reference_option 
);

Notice! 참고하고 있는 값이 삭제되거나 변경될 때 FK의 값은 어떻게 할 것인지 지정해야 함

→ `on delete reference_option`

→ `on update reference_option`

옵션

CASCADE: 참조값의 삭제/변경을 그대로 반영
SET NULL: 참조값이 삭제/변경 시 `NULL`로 변경
RESTRICT: 참조값이 삭제/변경되는 것을 금지
NO ACTION: `RESTRICT`와 유사
- MySQL은 `NO ACTION`과 `RESTRICT` 완전히 동일
- 표준 SQL: 한 트랜잭션 내의 여러 개의 SQL이 실행되는 동안에는 참조값이 삭제/변경되는 것을 허용
SET DEFAULT: 참조값이 삭제/변경 시 `default` 값으로 변경
- MySQL은 제대로 지원하지 않음.

→ MySQL에서 지원하는 reference_option은 `CASCADE`, `SET NULL`, `RESTRICT`

→ PostgreSQL은 5가지 모두 지원

ALTER

테이블이 생성된(create) 후에 테이블의 스키마를 변경할 때는 `ALTER TABLE` 문을 사용한다.

FK 옵션을 추가하는 경우의 예시

ALTER TABLE {테이블 명} ADD FOREIGN KEY (FK를 설정할 컬럼) REFERENCES {참조할 테이블}(참조할 테이블의 참조할 컬럼명)
    on update CASCADE
    on delete SET NULL;
    
# Example
ALTER TABLE department ADD FOREIGN KEY (leader_id) REFERENCES employee(id)
    on update CASCADE
    on delete SET NULL;

`department` 테이블의 `leader_id`에 `FK`를 설정한다.
`leader_id`는 `employee` 테이블의 `id` 컬럼을 참조한다.
나머지는 변경/삭제 시의 설정

윈도우에 프로메테우스 설치하기

jaamong — Fri, 3 May 2024 09:42:42 +0900

1. 아래 링크에서 각자 OS 맞는 프로메테우스를 다운로드

→ https://prometheus.io/download/

2. 다운로드 후 압축 풀기

3. 압축 푼 폴더에 들어가서 실행 프로그램인 `prometheus.exe` 클릭

4. 첫 실행인 경우, 클릭 시 아래와 같은 화면이 나타날 수 있다. 여기에서 `추가 정보`를 클릭.

5. `실행` 클릭

6. 실행하면 아래와 같은 터미널 창이 뜬다.

6. 프로메테우스의 기본 포트 `9090`, http://localhost:9090으로 접속

7. 끝!

[TIL / Spring] 설정 파일과 프로필

jaamong — Fri, 26 Apr 2024 09:40:33 +0900

스프링 부트 - 핵심 원리와 활용 | 김영한 - 인프런

김영한 | 실무에 필요한 스프링 부트는 이 강의 하나로 모두 정리해드립니다., 백엔드 개발자를 위한 스프링 부트 끝판왕! 실무에 필요한 내용을 모두 담았습니다. [임베딩 영상] 김영한의 스

www.inflearn.com

외부설정과 프로필1

오랜만에 Spring을 공부하고 있는데 설정 분리 등을 다 잊어버린 것 같아서 복기 겸 간단하게 정리한다.

DB 설정값을 코드 내부가 아닌 개발 서버와 운영 서버에 `application.properties`와 같은 파일을 두어 설정을 주입할 수 있다. 하지만 각 서버에 저장된 설정 파일을 관리하거나 변경 이력을 확인하기 어렵다.

이러한 문제점은 설정 파일을 프로젝트 내부에 포함해서 관리하여 해결할 수 있다. 설정 파일도 코드와 함께 빌드되게 하는 것이다.

프로젝트 내부에 코드와 함께 각 환경에 필요한 설정 데이터를 포함 및 관리
개발, 운영 설정 파일을 모두 포함하여 빌드
`app.jar`는 개발, 운영 두 설정 파일을 모두 가지고 배포됨
실행 시 어떤 설정 데이터를 읽어야 하는지 구분

스프링은 `프로필`이라는 개념을 지원하여 4번 과정을 해결한다.

application-xxx.properties

프로젝트 src > main > resources 디렉토리에 `application-xxx.properties` 파일을 생성한다. `xxx`에는 서버 환경을 구분하는 `dev`나 `prod` 등의 단어들이 보통 들어간다.

해당 파일에 필요한 설정들을 입력한다. 아래 파일은 `application-dev.properties`이다.

url=dev.db.com
username=dev_user
password=dev_pw

프로필 설정

dev 외에도 prod 설정 파일이 있을 수 있으므로, 이를 구분하기 위해 프로필을 설정해야 한다.

아래 이미지에서 `Edit Configurations...`를 클릭한다.

클릭 후 `Program arguments(CLI arguments)`에 다음과 같이 입력한다.

--spring.profiles.active=dev

# 또는

-Dspring.profiles.active=dev

위 옵션에 `dev`를 입력하면 `application-dev.properties` 파일에 적힌 설정값이 활성화된다. 마찬가지로 `prod`를 입력하면 `application-prod.properties` 파일에 적힌 값이 활성화된다.

한 파일에서 설정값 작성하기(application.properties)

`application.properties`에 모두 작성하는 방법도 있다. 아래와 같이 작성하면 dev와 prod 프로필의 설정값을 한 파일에 담을 수 있다.

spring.config.activate.on-profile=dev
url=dev.db.com
username=dev_user
password=dev_pw
#---
spring.config.activate.on-profile=prod
url=prod.db.com
username=prod_user
password=prod_pw

이때 프로필을 구분하기 위해 각 프로필 설정값 맨 위에 `spring.config.activate.on-profile=xxx`을 작성해야 하며, 프로필 설정값이 바뀌는 구간에서는 `#---`를 작성하여 구분해야 한다.

위와 같이 작성하고 Configuration에 동일하게 프로필을 지정해 주면 해당 설정값이 활성화된다.

default profile

Configuration에 아무런 프로필도 지정해주지 않으면 default로 설정된다. default는 `application.properties`에서 아래와 같이 지정하면 된다.

url=local.db.com
username=local_user
password=local_pw
#---
spring.config.activate.on-profile=dev
url=dev.db.com
username=dev_user
password=dev_pw
#---
spring.config.activate.on-profile=prod
url=prod.db.com
username=prod_user
password=prod_pw

맨 위에 아무런 프로필도 지정되지 않은 것이 default이다. 따라서 프로필을 지정하지 않으면 맨 위에 설정이 기본값으로 설정된다.

롤링 무중단 배포

jaamong — Fri, 19 Apr 2024 08:54:06 +0900

적용 전 준비할 코드

nginx.conf

worker_processes auto;

events {
    worker_connections 1024;
}

http {
    ...

    # for load balancing
    upstream project_server {
        server project_server2:8000;
        server project_server1:8000;
        keepalive 1024;
    }

    server {
        listen 80;  
        
        location / {
            proxy_pass http://project_server/;    # upstream 이름
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

            ...
        }

        ...
    }
}

무중단 배포의 전제조건은 이중화(로드밸런서)로, `upstream` 지시어로 설정할 수 있다.

docker-compose.yml

version: "3.5"

services:
  _build_image:
    image: project_django:4.2.6
    build: .
    
  project_server1: 
    image: project_django:4.2.6
    restart: always
    command: gunicorn project_server.backend.wsgi --bind 0.0.0.0:8000 --log-level debug --timeout=120
    ports:
      - "8000"  
    depends_on:
      - _build_image

  project_server2: 
    image: project_django:4.2.6
    restart: always
    command: gunicorn project_server.backend.wsgi --bind 0.0.0.0:8000 --log-level debug --timeout=120
    ports:
      - "8000" 
    depends_on:
      - _build_image

  nginx:
    image: project-nginx:latest    # tag the image with the name "nginx"
    container_name: project-nginx
    build: ./nginx  # Dockerfile location for Nginx
    restart: alway
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # read-only
    depends_on:
      - project_server1
      - project_server2
    ports:
      - "8000:80"
...

수동으로 하는 방법

✅ 전체 과정

배포 전 상태로 project_server1, project_server2 모두 로드밸런서(nginx)에 연결되어 있다.
project_server2를 로드밸런서에서 제거하고, project_server2에 배포를 진행한다.
project_server2에 배포가 완료되면, 다시 project_server2를 로드밸런서에 연결한다.
project_server1을 로드밸런서에서 제거하고, project_server1에 배포를 진행한다.
project_server1에 배포가 완료되면, 다시 project_server1을 로드밸런서에 연결한다.

Step1.

배포가 진행되는 동안 서비스가 멈추지 않는지(무중단) 확인하기 위해서 터미널 하나를 열여서 주기적으로 Nginx에 요청을 보낸다.

# 1초 간격으로 요청 (무한루프)
$ while true; do curl localhost:4100; ehco ""; sleep1; done

Step2.

project_server2를 로드밸런서에서 제거한다. nginx.conf의 `upstream` 서버 그룹에 아래와 같이 `down`을 추가한다.

...

upstream project_server {
    server project_server2:8000 down; 
    server project_Server1:8000;
}

...

Nginx 컨테이너에 아래와 같은 명령어를 전달하여 멈추지 않고 설정을 리로드 한다. 리로드 시 `exec`의 다음 인자는 docker-compose.yml의 `container_name`을 적어야 한다.

$ docker compose exec project-nginx service nginx reload

Step1에서 열어둔 터미널에서 project_server1에서만 응답이 오는 것을 확인하자.

project_server2의 배포를 진행한다.

$ docker compose up --build -d project_server2

Step3.

project_server2의 배포가 완료되면 project_server2를 로드밸런서에 연결하고 Nginx를 리로드 한다.

...

upstream project_server {
    server project_server2:8000; 
    server project_Server1:8000;
}

...

$ docker compose exec project-nginx service nginx reload

리로드 이후, Step1에서 열어둔 터미널에서 project_server1, project_server2로부터 응답이 오는 것을 확인한다.

Step4.

이번에는 project_server1의 배포를 진행한다. nginx.conf의 `upstream` 부분을 다음과 같이 수정하고 Nginx를 리로드 한다.

...

upstream project_server {
    server project_server2:8000; 
    server project_Server1:8000 down;
}

...

마찬가지로 Step1에서 열어둔 터미널에서 project_server2에서만 응답이 오는 것을 확인한다.

project_server1이 로드밸런서에서 제거됐으므로 project_server1의 배포를 진행한다.

$ docker compose up --build -d project_server1

Step5.

project_server1의 배포가 완료되었으므로 다시 로드밸런서에 연결한다.

...

upstream project_server {
    server project_server2:8000; 
    server project_Server1:8000;
}

...

마지막으로 Nginx를 리로드 한다.

$ docker compose exec project-nginx service nginx reload

먼저 열어둔 터미널에서 두 서버로부터 응답이 오는지 확인한다. 응답이 잘 온다면 모든 과정이 끝났다!

Deploy Shell Script

위에서 수동으로 진행한 롤링 무중단 배포 과정을 bash shell script로 작성했다. 수동으로 할 필요 없이 배포해야 할 때 아래와 같이 터미널에 입력하면 된다.

$ bash {쉘 스크립트 위치}/{쉘 스크립트 파일 이름}.sh
$ bash ./deploy.sh

#!/bin/bash

# cut connection to a server from the load-balancer(nginx)
# args: server name, server port, docker container name for nginx
cut_reload_nginx() {
	src="$1:$2"

	dest=$src
	dest+=" down;"

	src+=";"

	sed -i "s/$src/$dest/g" ./nginx/nginx.conf
	docker compose exec $3 nginx -s reload 
	sleep 10s
}

# connect a server to the load-balancer(nginx)
# args: server name, server port, docker container name for nginx
connect_reload_nginx() {
	dest="$1:$2"

	src=$dest
	src+=" down;"

	dest+=";"

	sed -i "s/$src/$dest/g" ./nginx/nginx.conf
	docker compose exec $3 nginx -s reload 
	sleep 10s
}

# deploy a server
# args: container name, env file path
deploy_server() {
	# 1. stop container 
	# 2. remove container
	# 3. up and build container

	echo ">> [deploy_server] Stop & Remove $1..."
	
	docker compose stop $1
	sleep 5s
	
	docker compose rm $1
	sleep 10s

	echo ">> [deploy_server] Up $1..."

	sudo docker compose --env-file $2 up $1 --build -d 
}

# health check for a container(server)
# args: url for health check(pass a url which is located at after localhost/)
health_check() {
	UP_CHECK=""
	URL="http://localhost/$1"

	echo ">> [health_check] URL=$URL"
	echo ">> [health_check] start..."

	while [ -z "$UP_CHECK" ]
	do 
		UP_CHECK=$(curl -s $URL) 
	done 

	echo ">> [health_check] finish..."
}

echo ""
echo ""
echo "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
echo ""
echo "Rolling Deployment Start"
echo "Author: Jaamong"
echo "Last Updated Date: 2024-0X-XX"
echo ""
echo "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
echo ""
echo ""


# ----- for project_server2 container -----
echo "> Nginx: Cut connection to project_server2..."
cut_reload_nginx "project_server2" "8000" "project-nginx"
echo ""

echo "> Deploy only project_server2..."
deploy_server "project_server2" "./project_server/config/.env"
echo ""

echo "> Health Check for project_server2..."
health_check "api/v1/health-check"
echo ""

echo "> Nginx: Connect to project_server2..."
connect_reload_nginx "project_server2" "8000" "project-nginx"
echo ""


sleep 10s


# ----- for project_server1 container -----
echo "> Nginx: Cut connection to project_server1..."
cut_reload_nginx "project_server1" "8000"
echo ""

echo "> Deploy only project_server1..."
deploy_server "project_server1" "./project_server/config/.env"
echo ""

echo "> Health Check for project_server1..."
health_check "api/v1/health-check"
echo ""

echo "> Nginx: Connect to project_server1..."
connect_reload_nginx "project_server1" "8000"
echo ""


sleep 10s


echo ""
echo "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
echo ""
echo "Rolling Deploy Finish"
echo ""
echo "++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++"
echo ""
echo ""

주의 사용 시 인자(argument)의 순서를 지켜서 입력해야 한다. 본인의 nginx.conf, docker-compose.yml과 맞지 않는 내용이 있을 수도 있으므로 반드시 스크립트 코드를 확인할 것.

cut_reload_nginx args
- server name: nginx와 연결을 끊을 서버 이름(컨테이너 명)
- server port: nginx와 연결을 끊을 서버 port
- nginx container name: docker-compose.yml에서 정의된 Nginx용 도커 컨테이너 이름
connect_reload_nginx args
- server name: nginx와 연결할 서버 이름(컨테이너 명)
- server port: nginx와 연결할 서버 port
- nginx container name: docker-compose.yml에서 정의된 Nginx용 도커 컨테이너 이름
deploy_server args
- container name: 배포할 컨테이너의 이름
- env file path: `.env` 파일 위치
health_check args
- health check URL: 헬스체크용 URL

[NGINX] HTTPS 서버 구성하기 (Let's Encrypt)

jaamong — Fri, 12 Apr 2024 08:45:47 +0900

목차

SSL/TLS

Certbot 설정과 SSL 적용

설정 과정

더미 인증서 생성

인증서 갱신 자동화

⭐️ 실제 진행 순서

SSL/TLS

전송 계승 상에서 클라이언트, 서버에 관한 인증 및 데이터 암호화 수행

클라이언트와 서버 양단간 응용 계층 및 TCP 전송 계층 사이에서 수행
보안용 프로토콜로 안전한 보안 채널을 형성하는 역할

SSL = Secure Socket Layer
TLS = Transport Layer Security
HTTPS = HTTP over SSL

HTTP에 SSL이 적용된 HTTPS를 이용하여 통신을 암호화하면 보안을 높일 수 있다. 이를 위해서는 SSL 인증서가 필요하다. 우리는 CA 중 하나인 Let's Encrypt를 통해 무료로 인증서를 발급받을 것이다. Let's Encrypt는 SSL 인증서를 발급해 주는 공인된 기관 중 하나이다.

Certbot은 Let's Encrypt에서 SSL 인증서 사용을 관리하는 무료 오픈소스 도구이다. certbot 명령을 사용하여 무료로 사용할 수 있는 SSL 인증서를 발급, 갱신, 삭제할 수 있다.

certbot을 활용하면 CLI를 통해 SSL 인증서를 발급받을 수 있지만, 90일마다 인증서를 재발급해야 하는 번거로움이 있다. 이러한 번거로움은 docker compose + nginx + certbot을 사용하여 이 과정을 자동화한 설정 파일을 제공하는 곳을 통해 해결할 수 있다!

Guide: https://pentacent.medium.com/nginx-and-lets-encrypt-with-docker-in-less-than-5-minutes-b4b8a60d3a71
GitHub: https://github.com/wmnnd/nginx-certbot

SSL/TLS

설정 과정

docker-compose.yml에 아래와 같이 nginx와 certbot 이미지를 정의한다. `image` 태그 명은 원하는 대로 작성하면 된다.
```
version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 

  certbot:
    image: certbot/certbot    

	...
```
`volumes` 블록 작성 시 nginx.conf의 위치를 확인하고 정확하게 작성한다. 나는 docker-compose.yml과 같은 위치에 nginx 디렉토리를 만들고 그 안에 nginx.conf를 만들었다.

이번에는 모든 요청을 HTTPS로 리다이렉트 하는 코드를 담은 nginx.conf를 작성한다. AWS EC2의 경우, 퍼블릭 IPv4 DNS가 아닌 Route53에 등록한 도메인을 입력한다.

server {
	listen 443 ssl;
	server_name {your_domain};  

	location / {
		proxy_pass http://{your_domain};  # upstream 사용 시 upstream 이름 작성
	}
}

server {
	listen 80;
	server_name {your_domain};  

	location / {
		return 301 https://$host$request_uri;  # redirects to https
	}
}

이제 nginx와 certbot을 연결한다. Let’s Encrypt는 도메인에서 `well-known URL`을 요청하여 도메인 검증을 수행한다. 도메인이 특정 응답(”challenge”)을 받으면 유효한 것이다. 해당 응답 데이터는 certbot에서 제공되므로, nginx 컨테이너가 certbot의 파일을 제공할 수 있는 방법이 필요하다.

우선 두 개의 docker 볼륨이 필요하다. 하나는 유효성 검사용, 하나는 실제 인증서용이다. 1번의 docker-compose.yml 파일에 코드를 추가한다.
```
- ./data/certbot/conf:/etc/letsencrypt
- ./data/certbot/www:/var/www/certbot
```
`data` 디렉토리는 수동으로 생성하지 않아도 된다.
```
version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    volumes:
    	- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 
        - ./data/certbot/conf:/etc/letsencrypt
        - ./data/certbot/www:/var/www/certbot

  certbot:
    image: certbot/certbot    
    volumes:
        - ./data/certbot/conf:/etc/letsencrypt
        - ./data/certbot/www:/var/www/certbot
	...
```

이제 nginx가 certbot에서 받은 challenge 파일을 제공할 수 있도록 하자. 아래 코드를 nginx.conf의 port 80 섹션에 추가한다.

location /.well-known/acme-challenge/ {
	root /var/www/certbot;
}

server {
	listen 443 ssl;
	server_name {your_domain};  

	location / {
    	proxy_pass http://{your_domain};  
	}
}

server {
	listen 80;
	server_name {your_domain};  

	location / {
		return 301 https://$host$request_uri;  
	}
		
	location /.well-known/acme-challenge/ {
		root /var/www/certbot;
	}
}

이제 HTTPS 인증서를 참조해야 한다. 곧 `생성될 인증서`와 인증서의 `private key`를 port 443 섹션에 추가해야 한다.

ssl_certificate /etc/letsencrypt/live/example.org/fullchain.pem;
ssl_certificate_key /etc/letencrypt/live/example.org/privkey.pem;

server {
	listen 443 ssl;
	server_name {your_domain};  

	ssl_certificate /etc/letsencrypt/live/{your_domain}/fullchain.pem;
	ssl_certificate_key /etc/letencrypt/live/{your_domain}/privkey.pem;

	location / {
		proxy_pass http://{your_domain};  
	}
}

server {
	listen 80;
	server_name {your_domain};  

	location / {
		return 301 https://$host$request_uri;  
	}
		
	location /.well-known/acme-challenge/ {
		root /var/www/certbot;
	}
}

보안과 관련된 코드 두 줄을 추가해 보자. 반드시 추가할 필요는 없으나, 보안을 생각한다면 넣는 것이 좋다.

include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letencrypt/ssl-dhparams.pem;

include /…/options-ssl-nginx.conf
options-ssl-nginx.conf 파일을 열어보면 SSL 관련 설정들이 적혀 있다.

# This file contains important security parameters. If you modify this file
# manually, Certbot will be unable to automatically provide future security
# updates. Instead, Certbot will print and log an error message with a path to
# the up-to-date file that you will need to refer to when manually updating
# this file. Contents are based on https://ssl-config.mozilla.org

ssl_session_cache shared:le_nginx_SSL:10m;
ssl_session_timeout 1440m;
ssl_session_tickets off;

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;

ssl_ciphers "...";

적혀있는 주석을 보면 알 수 있듯이, 해당 설정을 추가함으로써 Certbot에서 자동으로 보안 업데이트를 하도록 한다.

ssl_dhparam
`dhparam`을 사용하면 client와 server 간의 key를 exchange 할 때 perfect security를 보장한다.

아래가 최종 nginx.conf이다.

server {
	listen 443 ssl;
	server_name {your_domain};  

	# managed by Certbot
	ssl_certificate /etc/letsencrypt/live/{your_domain}/fullchain.pem;
	ssl_certificate_key /etc/letencrypt/live/{your_domain}/privkey.pem;
	include /etc/letsencrypt/options-ssl-nginx.conf;
	ssl_dhparam /etc/letencrypt/ssl-dhparams.pem;

	location / {
		proxy_pass http://{your_domain};  
	}
}

server {
	listen 80;
	server_name {your_domain};  

	location / {
		return 301 https://$host$request_uri;  
	}
		
	location /.well-known/acme-challenge/ {
		root /var/www/certbot;
	}
}

더미 인증서 생성

Nginx가 Let’s Encrypt 유효성 검증을 수행하도록 해야 하는데, Nginx는 인증서가 없으면 시작하지 않을 것이다. 그래서 더미 인증서를 먼저 생성해야 한다. 그리고 Nginx를 시작하고 더미 인증서를 지운 다음, 실제 인증서를 요청하는 과정으로 진행한다.

다행인 점은! 위 가이드 링크에서 이 과정을 자동화한 스크립트를 제공한다.

작업 디렉토리에 아래 명령어로 설치를 진행한다.

$ curl -L https://raw.githubusercontent.com/wmnnd/nginx-certbot/master/init-letsencrypt.sh > init-letsencrypt.sh

도메인과 이메일 주소를 변경하려면 스크립트를 수정해야 한다. 도메인에는 nginx.conf에 적었던 도메인과 동일한 주소를 입력하고, 이메일은 인증서가 만료될 때 알림을 받을 용도이다.
도커 볼륨의 디렉토리를 변경하는 경우, `data_path` 변수에도 적용해야 한다. 그러고 나서 아래 명령어를 실행한다.
```
$ chmod +x init-letsencrypt.sh 
$ sudo ./init-letsencrypt.sh
```
`./init-...` 명령으로 진행되지 않는다면 아래 `bash` 명령어로 진행한다.
```
$ sudo bash init-letsencyprt.sh
```

인증서 갱신 자동화

앞에서 언급한 것처럼 인증서는 유효기간이 있으므로 갱신해줘야 한다. 그런데 생각보다 갱신하는 주기를 잊기가 쉬워서 나중에 문제가 발생하고 나서 조치를 취하는 경우가 많다. 그러한 문제를 방지할 겸 인증서 갱신을 자동화해 보자.

docker-compose.yml의 `certbot` 섹션에 아래 코드를 추가한다. 이 코드는 Let’s Encrypt에서 권장하는 것처럼 12시간마다 인증서가 갱신되는지 확인한다.

entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot

  certbot:
    image: certbot/certbot    
    volumes:
    	- ./data/certbot/conf:/etc/letsencrypt
        - ./data/certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

...

docker-compose.yml의 `nginx` 섹션에 Nginx가 새로운 인증서를 리로드 하도록 코드를 추가해야 한다.

command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"

version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot

  certbot:
    image: certbot/certbot    
    volumes:
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

	...

⭐️ 실제 진행 순서

여기에서는 간략하게 실제 진행 순서를 다룬다. 위 순서대로 진행하면 좋겠지만, 더미 인증서를 발급받아야 하므로 그렇지 않다

docker-compose.yml을 작성한다.

version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot

  certbot:
    image: certbot/certbot    
	volumes:
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot
	...

nginx.conf를 작성한다.

server {
	listen 80;
	server_name {your_domain};  
		
	location /.well-known/acme-challenge/ {
    	root /var/www/certbot;
	}

	...
}

`docker compose up`을 진행한다.

아래 명령어를 입력하여 쉘 스크립트를 설치하고, 해당 스크립트를 수정한다. 스크립트에서 이메일과 도메인을 수정한 다음 실행한다.

$ curl -L https://raw.githubusercontent.com/wmnnd/nginx-certbot/master/init-letsencrypt.sh > init-letsencrypt.sh
$ chmod +x init-letsencrypt.sh
$ vi init-letsencrypt.sh 
$ sudo ./init-letsencrypt.sh

스크립트 실행 후 로그를 보면서 인증서 발급이 성공했는지 확인한다. 에러 발생으로 발급되지 않았다면 로그를 보면서 수정해 나간다.

인증서 발급이 완료되었으면 이제 HTTPS를 적용하자. nginx.conf를 수정한다.

server {
	listen 443 ssl;
	server_name {your_domain};  

	# managed by Certbot
	ssl_certificate /etc/letsencrypt/live/{your_domain}/fullchain.pem;
	ssl_certificate_key /etc/letencrypt/live/{your_domain}/privkey.pem;
	include /etc/letsencrypt/options-ssl-nginx.conf;
	ssl_dhparam /etc/letencrypt/ssl-dhparams.pem;

	location / {
		proxy_pass http://{your_domain};  
	}
}

server {
	listen 80;
	server_name {your_domain};  

	location / {
		return 301 https://$host$request_uri;  
	}
		
	location /.well-known/acme-challenge/ {
		root /var/www/certbot;
	}
}

인증서를 자동 갱신하도록 설정하자. docker-compose.yml 파일을 수정한다.

version: "3.5"

services:
  ...

  nginx:
    image: project-nginx:latest
    command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro  # 호스트 머신에서의 nginx.conf 위치:도커 컨테이너에서의 nginx.conf 위치 
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot

  certbot:
    image: certbot/certbot    
    volumes:
      - ./data/certbot/conf:/etc/letsencrypt
      - ./data/certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

	...

수정 완료 후 다시 `docker compose up`을 실행한다. 그리고 HTTPS 프로토콜이 적용됐는지 확인한다.
잘 적용됐다면 완료!

[TIL] ACM(ELB)와 NGINX

jaamong — Sun, 7 Apr 2024 10:37:27 +0900

상황

EC2를 사용하고 있어서 SSL 적용을 ACM으로 해보려고 했는데 실패하고 Let's Encrypt를 사용했다.

ACM SSL 인증서는 AWS Load Balancer, CloudFront, API Gateway를 통해서만 사용할 수 있다. 마침 로드 밸런싱을 Nginx로 하고 있었던 차에 ELB로 바꿔야지 하면서 ALB를 생성했었다.

생성하고 난 다음에, 문제는 ALB에서 보내는 헬스 체크 요청이 Nginx(웹서버)에 도달하지 않았다. ALB의 리스너 설정이나 대상 그룹 설정 등을 모두 확인했으나 Nginx에 요청이 도달하지 않았다.

나는 총 3개의 포트를 사용했던 것 같다. 아래 세 개 모두를 보안 그룹에 설정해 두었고, ALB 리스너 설정에도 추가해 두었다. (지금 생각해 보면 80, 443번 포트만 열어뒀어도 됐다) 요청을 처리하는 대상 그룹(target group) 문제인가 하고 확인해 봤는데, 인스턴스도 제대로 설정되어 있었다.

HTTP 요청을 위한 80번 포트
HTTPS 요청을 위한 443번 포트
Django 서버를 실행하고 있던 4100번 포트

이 와중에 4100번 포트의 헬스 체크는 `Healthy`로 잘 나타났고, 다른 포트들은 `Unhealthy`로 표시되었다.

알게 된 것

진행하고 있던 프로젝트는 Django를 사용하고 있었고 Django는 배포하려면 웹서버가 필요하다. 이때 사용하는 대표적인 웹서버로 Apache, Nginx가 있지만, 아파치로 사용하는 방법은 더 이상 지원하지 않는 것 같아서 Nginx로 채택했었다.

문제는 Nginx로 SSL을 설정하려면 서버(EC2 인스턴스)에 설치된 SSL 인증서가 필요했다.

ssl_certificate /etc/letsencrypt/live/{domain}/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/{domain}/privkey.pem;

간혹 이런 ACM + ELB + NGINX 조합으로도 SSL을 잘 적용한 글들이 보였는데, 또 다른 문제는 서버에서 실행되는 Nginx는 서버에 설치된 것이 아닌 도커 컨테이너 형태로 실행하고 있었다. (그래서였을까... 너무 힘들었다...)

이렇게 끊임없는 삽질로 알게된 것은 ACM으로 인증서를 얻어서 서버에 설치하는 것은 불가능하다는 사실이었다. 그래서 AWS에서 ELB나 CloudFront 등을 강제로 사용하게 하는 것 같다. 정확히는 "ELB에서 HTTPS를 사용하려면 ACM을 써라!"인 것 같지만...

ELB에서 HTTPS 리스너를 생성하려면 로드 밸런서에 한 개 이상의 SSL 서버 인증서를 반드시 배포해야 합니다. ...(중략)... AWS Certificate Manager(ACM)을 사용해 로드 밸런서를 위한 인증서를 생성하는 것이 좋습니다. ACM은 2048, 3072, 4096비트 길이의 RSA 인증서와 모든 ECDSA 인증서를 지원합니다. ACM은 Elastic Load Balancing과 통합하여 로드 밸런서에 인증서를 배포합니다. 자세한 내용은 AWS Certificate Manager 사용 설명서를 참조하세요.
- AWS Document ALB -

결국 ACM과 ELB를 포기했다! 어찌 됐건 SSL 적용은 필요했기 때문에 Let's Encrypt를 사용하여 인증서를 발급하고 Nginx에 설정했다.

최근에는 Nitro Enclaves라는 걸로 할 수 있는 것 같은데 별로 사용하지 않는 방법인 것 같다. 혹시 모르니까 링크 남겨두기...

https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave-refapp.html
https://aws.amazon.com/ko/about-aws/whats-new/2020/10/announcing-aws-certificate-manager-for-nitro-enclaves/

[AWS] ACM을 이용한 HTTPS 적용

jaamong — Fri, 5 Apr 2024 09:44:55 +0900

ACM

ACM(AWS Certificate Manager)은 우리의 AWS 웹사이트와 애플리케이션을 보호하는 SSL/TLS 인증서를 생성 및 저장, 갱신한다. 비용은 무료이며, 연마다 갱신할 필요가 없다.

AWS Certificate Manager를 통해 프로비저닝 되는 퍼블릭 SSL/TLS 인증서는 무료이다. 애플리케이션 실행을 위해 생성한 AWS 리소스에 대해서만 비용을 지불하면 된다.
https://ap-northeast-2.console.aws.amazon.com/acm/home?region=ap-northeast-2#/welcome

HTTPS 적용

Note ACM을 사용하려면 먼저 도메인이 등록되어 있어야 한다!

ACM 요청

AWS 메뉴에서 Certificate Manager에 접속한다. 그리고 아래 화면에서 요청을 클릭한다.

`퍼블릭 인증서 요청`을 선택하고 다음을 클릭한다.

아래 화면에서 먼저 준비해 둔 도메인 이름을 작성한다. 이때 `*.example.co.kr`처럼 와일드카드를 적용할 수 있다.

완전히 정규화된 도메인 이름(FQDN)
완전히 정규화된 도메인 이름(FQDN)은 인터넷 상의 조직 또는 개인의 고유한 이름이다. .com 또는 .org와 같은 최상위 도메인 확장명이 마지막에 위치한다. SSL/TLS 인증서로 보호하려는 사이트의 정규 도메인 이름을 입력한다(예: www.example.com). 동일한 도메인으로 여러 사이트를 보호하기 위해 와일드카드 인증서를 요청하려면 별표()를 사용한다. 예를 들어, .example.com은 www.example.com, site.example.com 및 images.example.com을 보호한다.

위 화면에서 아래로 스크롤하고, 검증 방법과 키 알고리즘을 아래 화면과 같이 선택한다. 그리고 맨 아래의 요청을 클릭한다.

이후 아래와 같은 화면이 나오면서 인증서 요청이 진행된다. 발급이 완료되면 상태가 발급됨으로 나온다.

다음으로 로드 밸런서를 생성해야 한다. 생성 방법은 아래 포스트를 참고!

2024.04.05 - [Architecture & Tool/AWS] - [AWS] ELB 생성

검증 상태가 보류 중으로 지속되는 경우

참고 링크

https://repost.aws/ko/knowledge-center/acm-certificate-pending-validation

위의 마지막 화면에서 인증서 ID를 클릭한다. 이후 도메인 영역에서 Route 53에서 레코드 생성을 클릭한다.

이후 Route 53으로 이동하면 유형이 `CNAME`인 레코드가 생성되어 있는 것을 확인할 수 있다.

[AWS] ELB 생성

jaamong — Fri, 5 Apr 2024 09:35:53 +0900

AWS의 ELB를 이용하여 로드밸런싱을 해보자! 그전에 ACM을 먼저 요청해야 한다.

2024.04.05 - [Architecture & Tool/AWS] - [AWS] ACM을 이용한 HTTPS 적용

ELB 생성

참고

https://aws-hyoh.tistory.com/147

ELB란?
- AWS Elastic Load Balancer(ELB) 쉽게 이해하기 #1
- Elastic Load Balancing이란 무엇인가요? - Elastic Load Balancing
ALB용 HTTPS 리스너 생성
- AWS CM과 로드 밸런스로 HTTPS로 변환하기
- Application Load Balancer용 HTTPS 리스너 생성 - Elastic Load Balancing

AWS EC2 왼쪽 메뉴에서 로드 밸런서를 클릭한다. 아래 화면에서 로드 밸런서 생성을 클릭한다.

create load balancer

아래 유형 중에서 `Application Load Balancer 아래의 생성 버튼을 클릭한다.

Select load balancer type

로드 밸런서 이름을 입력한다.

Basic configuration

네트워크 매핑 영역에서 EC2 인스턴스와 동일한 네트워크를 포함한 2개 이상의 영역을 선택한다. 예를 들어, 현재 사용 중인 인스턴스가 `ap-northeast-2a` 네트워크를 사용하고 있으면 해당 네트워크를 포함하여 선택하면 된다.

network region

잘 모르겠다면 모두 선택해도 괜찮다.

Network mapping

보안 그룹도 EC2 인스턴스와 동일한 것으로 선택한다. 모르겠다면 EC2의 ID를 클릭하여 보안 탭에서 확인하자.

instance security group

Security groups

리스너 및 라우팅 차례이다. 여기에서 HTTP 80 포트와 HTTPS 443 포트를 설정한다. 우선 아래 화면에서 대상 그룹 생성을 클릭한다.

Listeners and routing

그룹 세부 정보 지정의 기본 구성에서 대상 유형은 인스턴스로 선택하고, 대상 그룹 이름을 입력한다.

Specify group details - Basic configuration

나머지는 그대로 두고, 맨 아래로 스크롤을 내려서 다음을 클릭한다.

상태 검사 경로는 로드 밸런서와 연결되어 있는 인스턴스가 살아있는지 정기적으로 확인하는 health check를 위한 경로이다. 만일 접속이 불가능한 경우 해당 인스턴스를 불능상태로 인식하고 트래픽을 보내지 않는다.

아래 화면에서 로드 밸런서를 적용할 인스턴스를 선택하고, 아래에 보류 중인 것으로 포함을 클릭한다.

그다음 대상 그룹 생성을 클릭한다.

생성이 완료되면 아래와 같은 화면이 나온다.

다시 리스너 및 라우팅으로 돌아와서 리스너 설정을 진행한다. 리스너 태그 추가를 클릭하여 HTTP, HTTPS 모두 생성하며, 모두 HTTP 대상 그룹을 선택한다. 생성한 대상 그룹이 보이지 않으면 옆에 새로 고침 버튼을 클릭하자.

Listners and routing

보안 리스너 설정에서 EC2 인스턴스에 적용한 ACM을 선택한다.

Secure listener settings

이후 로드 밸런서 생성을 클릭한다.

create load balancer

이후 아래 화면에서 아래로 스크롤하고, 리스너 및 규칙에서 `HTTPS`를 선택합니다. 선택한 상태에서 리스너 관리 > SNI용 SSL 인증서 추가를 클릭합니다.

Listeners and rules

이동된 화면에서 이전에 발급받은 ACM을 선택하고 아래에 보류 중인 것으로 포함을 클릭한다.

Add certificate to listener

그리고 보류 중인 인증서 추가를 클릭한다.

번외.

나중에 필요한 리스너나 규칙을 추가하려면 로드 밸런서 창으로 돌아와 리스너 및 규칙에서 리스너 추가를 클릭하면 된다.

로드 밸런서 대상 그룹 unhealthy 이슈

참고

✅ Health Check URL

HTTPS 적용이 안 돼서 어떤 문제인지 확인해 봤더니, 등록한 모든 대상 그룹의 상태가 `Unhealthy`로 나와 있었다!

생각해 보니 대상 그룹의 상태 확인을 위한 경로를 `root url(/)`로만 지정해 놓은 상태였다. 그래서 헬스 체크를 위한 코드를 추가하고 상태 확인 경로를 수정했다.

# views.py
@api_view(['GET'])
def health_check(request):
    """
    헬스 체크용 함수 -> 별도의 로직 필요없음
    """
    return Response(status.HTTP_200_OK)
    
# urls.py
urlpatterns = [
    ...
    path('health-check', views.health_check),
]

그리고 Django를 사용한 개발이므로 prod.py(==settings.py)의 `ALLOWED_HOSTS`에 EC2 인스턴스의 프라이빗 IPv4 주소를 추가했다.

...
ALLOWED_HOSTS = [
    # 여기서는 실제 주소 대신 문자열로 대체
    
    "ALLOWED_HOST_IP_PUB", 
    "ALLOWED_HOST_IP_PRI",  # here
    "ALLOWED_HOST_DOMAIN",
]
...

이후 상태가 `Healthy`로 변한 것을 확인할 수 있다!

[AWS] EC2 인스턴스 용량(EBS 볼륨) 확장

jaamong — Fri, 29 Mar 2024 10:51:30 +0900

EC2 인스턴스 용량 확장

디스크 용량 확인

$ df -hT

리눅스 `df` 명령어는 파일 시스템 디스크의 용량을 확인할 때 사용한다. `-h` 옵션은 사람이 보기에 편한 용량 크기로 출력한다. `-T` 옵션은 파일의 타입(Type)을 보여주는 항목을 추가한다.

df -hT 결과 화면

현재 사용 중인 용량을 보니 인스턴스의 최대 용량인 8 GiB가 다 찼다! 추후 무엇을 설치할 수도 있고, 원활한 서비스 운영을 위해 인스턴스의 용량을 늘려야 한다.

인스턴스 볼륨(EBS) 추가

아래 화면에서 인스턴스가 사용하고 있는 블록 디바이스를 확인하고, `볼륨 ID`를 클릭한다.

클릭하면 아래와 같은 화면이 나타난다.

`볼륨 ID`를 오른쪽 마우슨 버튼으로 클릭한다. 아래 화면이 나오면 `볼륨 수정`을 클릭한다.

크기를 수정하고 `수정` 버튼을 클릭한다.

운영 중인 서비스가 도커 컨테이너를 여러 대를 띄우다 보니 적어도 모두 띄웠을 때 서버가 다운되지 않을 정도의 용량이 필요했다. 그래서 아래 명령어를 입력하여 현재 서비스가 사용하고 있는 리소스를 확인했다. 아래 명령어 이외에도 사용하고 있는 도커 용량을 확인할 수 있는 명령어들을 찾아서 얼마만큼의 리소스가 필요한지 정리하면 좋을 것 같다.
$ docker system df -v

`수정` 버튼을 클릭한다.

그러고 나면 아래처럼 수정 중이라는 안내가 나온다. 적용까지는 몇 분 정도 소요될 수 있다.

적용이 완료되면 아래처럼 적용된 크기를 확인할 수 있다.

파티션 크기 늘리기

리눅스의 `lsblk` 명령어는 블록 장치 관련 작업을 도와주는 유틸리티 CLI 도구로, 블록 장치를 나열한다. 아래 사진은 볼륨 크기를 확장하기 전 상태다.

볼륨 크기 확장 전 lsblk

첫 번째 열의 각 의미는 순서대로 장치 이름, 해당 주 및 부 장치 번호, 장치가 제거 가능한지 여부(제거 가능한 경우 1), 장치 크기, 장치가 읽기 전용인지 여부, 장치 유형(디스크, 파티션 등), 마지막으로 장치 마운트 지점(사용 가능한 경우)이다.

아래 사진은 볼륨 크기를 확장한 후 상태이다. 디스크(disk)의 크기가 32G로 늘어난 것을 확인할 수 있다. 이제 볼륨의 파티션을 확장해야 한다.

볼륨 크기 확장 후 lsblk

위 사진에서 `xvda`는 물리적인 디스크를 의미하고, `xvda1`, `xvda14`, `xvda15`는 파티션을 의미한다. 디스크 영역은 32G로 늘어났지만, 파티션의 영역은 여전히 8G만 사용하고 있는 것을 확인할 수 있다.

즉 리눅스는 32GB의 디스크를 가지고 있지만, 실제로는 8GB만 사용할 수 있는 상태이다.

아래 명령어를 입력하여 파티션을 확장하자.

$ sudo growpart {디스크명} 1
$ sudo growpart /dev/xvda 1

이후 아래 명령어를 입력하여 파티션이 확장되었는지 확인한다.

$ lsblk

확장 전과 비교했을 때 파티션의 크기가 확장된 것을 확인할 수 있다.

ext4 파일 시스템의 크기 늘리기

이제 디스크 공간을 확장해야 한다. 사용하고 있는 파일 시스템에 바뀐 파티션의 크기를 적용해야 한다.

아래 명령어로 마운트 영역을 확인한다.

$ df -hT

/dev/root를 보면 여전히 8GB만 사용하고 있다.

이제 디스크 공간을 확장하자. (위 사진에서 `Type` 항목이 `ext4`인 경우)

$ sudo resize2fs {파일시스템명}
$ sudo resize2fs /dev/root

이제 공간 확장이 완료되었다!

AWS 공식 문서

OS 및 사양에 따라 진행하면 된다. 사용하는 인스턴스의 파일 시스템이 무엇인지 잘 확인하고 진행하자.

https://docs.aws.amazon.com/ebs/latest/userguide/recognize-expanded-volume-linux.html

번외. EBS 볼륨 유형 gp2 vs gp3

gp3는 gp2보다 20% 가량 비용을 아낄 수 있으면서, 볼륨 크기와 관계없이 3,000 IOPS의 기준 성능과 125Mib/s의 처리량을 제공한다. gp2는 고성능의 IO가 필요한 시스템에서는 불필요하게 더 많은 스토리지 볼륨이 요구된다.

IOPS(Input/Output Operations Per Second)란 EBS 볼륨의 성능을 측정하는 중요한 지표 중 하나로, 초당 입출력 작업 수를 나타냅니다. 즉, 높으면 높을수록 파일의 읽고 쓰는 것이 빨라진다는 뜻이다.
IOPS를 계산할 때는 사용하는 애플리케이션이나 데이터베이스의 I/O 최대크기를 확인해야 한다.

EBS 볼륨 유형의 요금에 관한 자세한 정책 및 내용은 아래 링크를 참고!

https://aws.amazon.com/ko/ebs/pricing/

[AWS] EC2 인스턴스 내 Docker 설치와 Django 프로젝트 설정

jaamong — Sat, 23 Mar 2024 09:21:05 +0900

이 글에서는 아래의 주제를 다룹니다.

인스턴스 내 Docker 설치
프로젝트 클론
파이썬 설치
가상환경(venv) 설치
패키지(requirements.txt) 설치
서버 실행 (docker compose)

Notice EC2 AMI - Ubuntu 22.04 LTS 기준 작성

인스턴스 내 Docker 설치

Ubuntu에서 Docker를 설치하는 방법은 Docker 공식 홈페이지에 있는 Ubuntu 설치를 보고 따라 하면 된다.

인스턴스에 접속한다. 접속 방법은 vscode나 터미널 등으로 하면 된다. vscode로 접속하는 방법은 여기를 참고!
접속(서버 연결)이 완료됐다면 터미널에 아래와 같이 입력하여 우분투 시스템 패키지를 업데이트한다.
```
$ sudo apt-get update
```

Docker의 `apt` 레포지토리를 설정한다.

# Add Docker's official GPG key:
$ sudo apt-get update
$ sudo apt-get install ca-certificates curl
$ sudo install -m 0755 -d /etc/apt/keyrings
$ sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
$ sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
$ echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
$ sudo apt-get update

Docker 패키지를 설치한다. 설치 시 가장 최신 버전을 원하는 경우 아래와 같이 입력한다.
```
$ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
마지막으로 잘 설치됐는지 확인하기 위하여 아래 명령어를 입력한다.
```
$ sudo docker run hello-world
```

입력 후 터미널에 나오는 문구가 아래와 같다면 정상적으로 설치가 완료된 것이다.

Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
c1ec31eb5944: Pull complete 
Digest: sha256:4bd78111b6914a99dbc560e6a20eab57ff6655aea4a80c50b0c5491968cbc2e6
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    (amd64)
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:
 https://hub.docker.com/

For more examples and ideas, visit:
 https://docs.docker.com/get-started/

번외.

Docker 설치 이후 `docker ps` 명령을 입력했을 때 `permission denied` 에러가 발생하는 경우 아래와 같이 진행한다`.

docker 그룹에 user 추가

$ sudo usermod -aG docker {계정명}
$ cat /etc/group | grep docker

서버 재접속 후 `docker ps` 확인

1번 방법으로 해결이 안 된다면 직접 권한을 부여해야 한다.
```
$ sudo chmod 666 /var/run/docker.sock
```
위 명령어는 /var/run/docker.sock 파일의 소유자, 그룹, 다른 모든 사용자들의 권한을 읽기와 쓰기로 설정한다.

프로젝트 클론

클론 전 EC2 인스턴스에 본인의 계정을 추가한다. 관련 방법은 여기 링크에서 번외 중 계정 추가를 참고한다.

레포지토리 클론

클론 전에 EC2 인스턴스에 본인의 계정을 추가했다면 `sudo su {계정명}`으로 계정 스위칭을 진행한다. 그다음 `git config --global`을 이용하여 본인의 버전 관리 시스템(GitHub, Gitea,...) 계정을 추가한다. 자세한 Git 계정 설정은 여기 링크를 참고한다.

이제 클론! 터미널에 아래 명령어를 입력한다.

$ git clone {git_remote_url}.git

서브 모듈이 있다면 아래와 같이 입력한다. 단, 아래 명령어는 Git 2.13 버전부터 가능하니 그전에 `git --version` 명령어로 버전을 확인하자.

$ git clone --recurse-submodules <remote-repo-url>

버전을 충족하지 않는 경우 여기 글을 참고하자.

디렉터리 위치 옮기기

Ubuntu에서 각 디렉터리의 의미를 확인해 보고, 적절한 곳에 클론 받은 디렉터리/프로젝트를 옮겨보자.

리눅스 디렉토리 종류와 특징

디렉토리란 파일 저장소를 의미하며, 리눅스 디렉토리는 최상위 디렉토리를 기준으로 하위 디렉토리들이 존...

blog.naver.com

나는 `/home/`에 위치시켰다. (그냥 root에 놓을 걸 그랬나...)

$ mv {현재 위치}/{repo 이름} /home/

`Permission denied` 에러 발생 시 `mv` 명령어 앞에 `sudo`를 붙여서 다시 실행한다.

파이썬 설치

파이썬 설치 참고 자료
https://mungto.tistory.com/289
https://ko.linux-console.net/?p=15722

⚠️ SSL 적용

파이썬 설치 전에 OpenSSL을 설치 및 적용해야 한다. 그렇지 않으면 pip 사용 시 아래와 같은 에러를 만날 수 있기 때문이다...

(.venv) {계정명}@{IP}:/home/{프로젝트명}$ pip install -r requirements.txt
WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError("Can't connect to HTTPS URL because the SSL module is not available.")': /simple/aiobotocore/
WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError("Can't connect to HTTPS URL because the SSL module is not available.")': /simple/aiobotocore/
WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError("Can't connect to HTTPS URL because the SSL module is not available.")': /simple/aiobotocore/
WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError("Can't connect to HTTPS URL because the SSL module is not available.")': /simple/aiobotocore/
WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError("Can't connect to HTTPS URL because the SSL module is not available.")': /simple/aiobotocore/
Could not fetch URL https://pypi.org/simple/aiobotocore/: There was a problem confirming the ssl certificate: HTTPSConnectionPool(host='pypi.org', port=443): Max retries exceeded with url: /simple/aiobotocore/ (Caused by SSLError("Can't connect to HTTPS URL because the SSL module is not available.")) - skipping
ERROR: Could not find a version that satisfies the requirement aiobotocore==2.5.0 (from versions: none)
ERROR: No matching distribution found for aiobotocore==2.5.0
WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
Could not fetch URL https://pypi.org/simple/pip/: There was a problem confirming the ssl certificate: HTTPSConnectionPool(host='pypi.org', port=443): Max retries exceeded with url: /simple/pip/ (Caused by SSLError("Can't connect to HTTPS URL because the SSL module is not available.")) - skipping

SSLError("Can't connect to HTTPS URL because the SSL module is not available.

python3.7을 설치한 후 pip까지 설치가 끝난 후 pip로 모듈을 다운로드 받을려고 할때 아래와 같은 에러가 ...

blog.naver.com

만일 벌써 발생했다면, 파이썬을 제거한 후 재설치해야 한다. 인터넷에 나오는 대중적인 방법과 여러 방법을 다 시도했을 때 다 실패해서 재설치했다 . (아마 찾으면 대부분 ` --trusted-host` 옵션을 알려주는데 보안적으로 좋지 않은 방법이라 별로 추천하고 싶지 않다. 그냥 깔끔하게 재설치하자^^) Ubuntu 환경에서 특정 버전의 파이썬을 제거하는 방법은 여기를 참고하자.

이제 OpenSSL 및 관련 라이브러리를 설치한다.

$ sudo apt-get update
$ sudo apt-get install openssl libssl-dev

완료했으면 파이썬 설치로 넘어간다!

파이썬 설치

우분투 시스템 패키지를 업데이트한다.
```
$ sudo apt-get update
```
다음 링크에 들어가서 원하는 버전을 받을 수 있는 주소를 찾는다.
→ https://www.python.org/ftp/python/

예를 들어, 3.8.18 버전이라면 다음과 같은 주소가 된다.
→ https://www.python.org/ftp/python/3.8.18/
우분투에서 2번에서 찾은 경로를 이용하여 다운로드를 진행한다.
```
$ sudo wget https://www.python.org/ftp/python/3.8.18/Python-3.8.18.tgz
```
다운로드를 완료하면 압축을 풀고 해당 폴더로 이동한다.
```
$ sudo tar zxf Python-3.8.18.tgz
$ cd Python-3.8.18/
```
파이썬 설치에 필요한 필수 종속성과 패키지를 설치하기 전에 종속성을 설치하려면 다중 저장소 저장소를 활성화해야 한다고 한다. 아래 주어진 명령을 실행하여 활성화할 수 있다.
```
$ sudo apt-add-repository multiverse
```

종속성 설치를 진행한다.

$ sudo apt-get install build-essential checkinstall 
$ sudo apt-get install libreadline-gplv2-dev libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev

설치가 완료되었으면, 컴파일을 진행한다. 위치는 압축을 해제한 파이썬 디렉터리 안이다.
```
$ sudo ./configure --enable-optimizations
```
이제 적용하는 단계로, 기존 Python 바이너리를 덮어쓰는 것을 방지한다.
```
$ sudo -H make altinstall
```
완료 후 파이썬 버전을 확인한다.
```
$ python3 --version
```
버전이 바뀌지 않았다면 `PATH`를 변경한다. 버전이 바뀌었다면 변경은 넘어가도 된다.

PATH 변경

아래 명령어로 위치를 찾는다.
```
$ which python
/usr/bin/python3
```
해당 경로를 기억하고 설정을 위해 아래 명령어를 입력한다.
```
$ vim ~/.bashrc
```
파일 맨 하단에 아래와 같이 입력하고 vim을 종료한다. `PATH`와 `=` 사이는 띄어쓰기 없이 입력해야 한다.
```
...

export PATH={which python 결과}:$PATH
```
`PATH`에 1번에서 입력한 명령어의 결과물을 입력한다. 아래는 예시다.
```
...

export PATH=/usr/bin/python3:$PATH
```
변경한 내용을 적용하기 위해 아래와 같이 입력한다.
```
$ source ~/.bashrc
```
버전을 확인한다.
```
$ python3 --version
```

가상환경(venv) 설치

우분투 시스템 패키지를 업데이트한다.
```
$ sudo apt-get update
$ sudo apt-get upgrade
```

`pip`가 설치되어 있지 않다면, `python3-pip`를 설치한다.

$ pip --version  # pip 버전 확인
$ sudo apt-get install python3-pip  # 없으면 설치

파이썬 가상환경 패키지를 설치한다.
```
$ sudo apt-get install python3-venv
```
가상환경을 설치할 곳으로 이동하여 다음 명령어를 입력하여 가상환경을 생성한다. 이때 개발 환경에 맞는 파이썬 버전의 가상환경을 생성한다.
```
# 터미널에 python을 입력했을 때 나오는 파이썬 버전으로 생성
$ python3 -m venv {원하는 이름}
$ python3 -m venv .venv

# 또는 특정 버전의 파이썬 버전으로 생성
python3.8 -m venv .venv
```
꼭 `.venv`로 할 필요는 없으나, 대부분 해당 이름으로 진행한다

설치가 완료되었으면 가상환경을 활성화할 수 있다.

$ source .venv/bin/activate  # 활성화
$ deactivate  # 비활성화

패키지(requirements.txt) 설치

위에서 Django 프로젝트를 클론 했을 때 `requirements.txt` 파일이 있을 수 있다. 해당 파일을 이용하여 필요한 패키지들을 설치한다.

$ python3 -m pip install -r requirements.txt

⚠️ `pip` 사용 시 `sudo`를 함께 사용하지 마세요. 나중에 권한 문제가 발생합니다.

pip 에러 관련 1

설치 중에 특정 패키지 구간에서 에러가 난다면, 에러문구를 잘 보고 반드시 구글링 하자. 대부분 필요한 종속성 중에 없는 것을 설치하라고 알려줄 테니, 해당 종속성을 설치하면 된다.

pip 에러 관련 2

가상환경에서 패키지 설치 시 아래와 동일한 에러가 나면 권한 설정을 해야 한다.

ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: '/venv_3.8/lib/python3.8/site-packages/sqlparse'
Check the permissions.

아래 명령어로 권한 설정을 한다.

$ sudo chown -R $(whoami) {가상환경 경로}
$ sudo chown -R $(whoami) /home/{프로젝트명}/.venv/

서버 실행 (docker compose)

모든 환경 설정이 완료됐다면, 이전 서버에서 사용했던 그대로 docker compose를 실행하고 오류가 발생하는지 확인하자.

$ docker compose up --build

DB 연결 확인

잘 띄워졌으면 DB 연동에도 문제가 없는 상태일 것이다. 도커 컨테이너를 띄우는 과정에서 DB 연동으로 에러가 발생한다면 아래 항목을 확인한다.

보안 그룹에서 해당 DB를 위한 포트(port)가 열려있는지
해당 DB에 접근 권한이 있는지
DB 계정을 정확하게 작성했는지
접근하는 EC2 인스턴스의 IP를 잘 기입했는지

API 호출 확인

모두 해결하고 컨테이너도 잘 띄워졌다면 이번에는 API 호출을 테스트한다. 포스트맨을 이용하여 API를 호출해 보자.

아래 사진은 포스트맨에서 API를 호출한 화면이다. `host_pub_ip` 변수는 EC2 인스턴스의 public IP, `host_port`에는 Django 서버용으로 도커 컨테이너에서 열려있는 port를 의미한다. https 적용 전이므로 http 프로토콜로 요청한다.

이제 AWS EC2 인스턴스 생성 및 환경 설정, Django 서버 실행하기까지 모두 끝났다!

VSCode로 AWS EC2 인스턴스 접속

jaamong — Sat, 16 Mar 2024 08:39:01 +0900

Visual Studio Code로 AWS EC2 인스턴스에 접속하는 방법을 다룬다.

과정

1. 설치된 vscode에 접속한다. vscode에 remote 관련 extension이 없다면 설치해야 한다.

아래 세 개를 설치

2. vscode 단축키 `ctrl/command + shift + p`를 입력하여 아래와 같은 검색창이 나타나도록 한다.

3. 검색창에서 "open ssh configuration file"을 입력하여 클릭한다.

4. 클릭하면 아래와 같은 화면이 나온다. 아래 화면에서 채워야 할 요소들이 있다.

Host {vscode에서 접속할 인스턴스의 이름}
    HostName {EC2 인스턴스의 “퍼블릭 IPv4 DNS” 또는 “퍼블릿 IPv4 주소”}
    User {별다른 설정이 없다면, ubuntu로 적기}
    IdentityFile {인스턴스 생성 시 같이 생성한 키페어(.pem) File 위치}

5. 위와 같이 작성하고 저장한다. 다시 vscode 단축키 `ctrl/command + shift + p`를 입력하여 검색창을 띄우고, "connect to host"를 입력하여 클릭한다.

연결 시 "Permission denied(Public Key)"와 같은 에러가 발생하면 해당 `.pem` 파일의 권한을 `400`으로 바꾸자. 그리고 해당 파일의 위치가 `.ssh` 폴더 안이 아니면, 폴더 안으로 옮겨주자.
$ chmod 400 ~/.ssh/{pem_key_name}.pem

6. 클릭하여 연결 후, 에러가 없다면 성공!

[AWS] Route 53으로 도메인 호스팅 하기

jaamong — Sat, 9 Mar 2024 09:23:11 +0900

AWS Route 53

Amazon Route 53 은 가용성과 확장성이 뛰어난 클라우드 Domain Name System (DNS) 웹 서비스이다. Route 53는 도메인 구입부터 네임서버 등록까지 DNS에 필요한 모든 기능이 있고, 모니터링 기능까지 제공한다.

다른 도메인 등록 기관(가비아, 후이즈 등)에 비해 가격이 비슷하거나 저렴하고, 등록 외에 부가적인 기능 제공 및 안정성, GUI를 제공해 관리가 수월하다.

또한 Route 53은 사용자의 요청을 Amazon EC2 인스턴스, Elastic Load Balancing 로드 밸런서, Amazon S3 버킷 등 AWS에서 실행되는 인프라에 효과적으로 연결하고, AWS 외부의 인프라로 라우팅 하는데도 사용이 가능하다.

Route 53으로 도메인 호스팅 하기

하기 전에 도메인은 Route 53에서 구입하거나, 다른 곳에서 구입하여 준비한다.

AWS Route 53에 접속하여 호스팅 영역을 클릭한 후 아래 화면에서 호스팅 영역 생성을 클릭한다.

클릭 후 아래 화면에서 도메인 이름을 입력한다. 유형은 퍼블릭 호스팅 영역을 선택한다.

호스탱 영역 생성을 클릭한다.

생성이 완료되면 아래와 같은 화면이 나온다.

위 화면의 유형 NS(Name Server)에 해당하는 값/트래픽 라우팅 대상 4개의 값이 모두 필요하다. 해당 값들을 도메인을 구입한 곳에서 네임 서버(NS)로 등록한다. 네임서버 등록 시 맨 뒤에 `.`은 들어가지 않으니 주의!

다시 AWS Route 53으로 돌아와서, 아래 화면에서 레코드 생성을 클릭한다.

레코드 유형을 선택하고 값을 채워준다. 다 입력했으면 레코드 생성을 클릭한다.

레코드 유형은 위 화면과 같이 `A-IPv4 주소 및 일부 AWS 리소스로 트래픽 라우팅`을 선택하고, 값에는 EC2 인스턴스의 `퍼블릭 IPv4 주소` 또는 할당받은 `탄력적 IP 주소`를 입력한다.

끝났다!

Ubuntu 환경에서 특정 버전의 파이썬 제거하기

jaamong — Fri, 8 Mar 2024 21:21:31 +0900

우선 삭제 전에 가상환경을 만들어 놨다면 비활성화를 한 후, 가상환경을 제거한다.
```
$ deactivate 
$ rm -rf {가상환경이름}
```
설치했던 파이썬의 위치를 확인해야 한다. 보통 `/usr/local/bin`에 위치한다. 아래 명령어로 특정 파이썬 버전의 디렉터리가 존재하는지 확인한다.
```
$ ls -al /usr/local/bin
```
존재한다면 아래 명령어로 제거한다. 또한 파이썬과 함께 해당 버전을 가진 이름의 디렉토리가 있다면 해당 디렉터리 및 파일도 제거한다.
```
$ sudo rm /usr/local/bin/{파이썬 버전} 
$ sudo rm /usr/local/bin/python3.8
```
파이썬 관련 디렉토리 또한 삭제해야 한다. 보통 `/usr/local/lib`에 위치한다. 3번과 마찬가지로 파이썬과 함께 해당 버전을 가진 이름의 디렉토리 및 파일이 있다면 제거한다.
```
$ sudo rm -rf /usr/local/lib/{파이썬 버전} 
$ sudo rm -rf /usr/local/lib/python3.8
```