문제

avg=4.15s / p(90)=5.73s / p(95)=6.09s

300명이 동시에 주문 요청을 보내면 DB 커넥션 풀이 금방 고갈된다. 커넥션을 얻지 못한 요청들은 줄을 서서 대기하게 되고, 그게 응답 지연으로 이어지는 구조였다.

HikariCP란? Spring Boot에서 기본으로 사용하는 DB 커넥션 풀 라이브러리다. 커넥션 풀이란 DB 연결을 미리 여러 개 만들어두고 요청이 들어올 때마다 재사용하는 방식인데, 풀 사이즈가 너무 작으면 동시 요청이 몰릴 때 병목이 생긴다. 기본값은 maximum-pool-size: 10으로, 동시에 10개의 DB 연결만 허용한다.

해결

application-prod.yaml에 Hikari 설정이 아예 없었기 때문에 아래 설정을 추가해주었다.

hikari:
  maximum-pool-size: 30      # 최대 커넥션 수 (기본값 10 → 30으로 증가)
  minimum-idle: 10           # 유휴 상태에서 유지할 최소 커넥션 수
  connection-timeout: 30000  # 커넥션 획득 대기 최대 시간 (30초)
  idle-timeout: 600000       # 유휴 커넥션 유지 시간 (10분)
  max-lifetime: 1800000      # 커넥션 최대 수명 (30분)

핵심은 maximum-pool-size를 10에서 30으로 늘린 것이다. 동시에 처리할 수 있는 DB 연결이 3배로 늘어나니 대기 줄이 줄어들 수밖에 없다.

결과

설정 몇 줄 추가했을 뿐인데 평균 응답시간이 4.15초 → 1.69초로 약 60% 개선됐다.

코드 한 줄 안 바꾸고 설정만으로 이 정도 성능 차이가 난다는 게 인상적이었다. 기본값이 항상 최선은 아니다. 특히 트래픽이 몰리는 서비스라면 커넥션 풀 사이즈는 반드시 확인하고 튜닝해야 한다는 걸 이번에 직접 체감하게 되었다.

도메인은 https://pposiraegi.cloud/login 이며, 타임딜 서비스 특성상 특정 시간대에 트래픽이 순간적으로 폭증하는 상황이 발생한다. 이 트래픽을 실제로 버틸 수 있는지 검증하기 위해 부하 테스트 도구인 k6를 사용해보기로 했다.

k6란? JavaScript로 테스트 스크립트를 작성해 HTTP 요청을 대량으로 보내고, 응답 시간·성공률 등을 측정할 수 있는 오픈소스 부하 테스트 도구다.

k6 설치

공식 설치 문서: https://grafana.com/docs/k6/latest/set-up/install-k6/

Windows 환경이므로 PowerShell에서 아래 명령어를 실행한다.

winget install k6 --source winget

k6 테스트 파일 작성

test.js 파일을 생성하고 아래 스크립트를 작성했다.

import http from 'k6/http';
import { sleep, check } from 'k6';

export const options = {
  vus: 300,       // 동시 접속 가상 유저 300명
  duration: '30s', // 30초 동안 테스트 실행
};

// 테스트 시작 전 1회 실행 - 로그인해서 토큰을 가져옴
export function setup() {
  const res = http.post(
    'https://pposiraegi.cloud/api/v1/auth/login',
    JSON.stringify({ email: 'test@test.com', password: '123456' }),
    { headers: { 'Content-Type': 'application/json' } }
  );
  console.log('로그인 응답:', res.status, res.body);
  const token = res.json('data.accessToken');
  console.log('토큰:', token);
  return { token };
}

// 가상 유저 300명이 30초 동안 반복 실행하는 시나리오
export default function (data) {
  const body = `{"orderItems":[{"skuId":839470480585919574,"quantity":1}]}`;

  const res = http.post(
    'https://pposiraegi.cloud/api/v1/orders',
    body,
    {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${data.token}`,
      }
    }
  );
  console.log('주문 응답:', res.status, res.body);
  check(res, {
    'status is 200': (r) => r.status === 200,
  });
  sleep(1);
}

작성 후 아래 명령어로 실행한다.

k6 run test.js

실행 결과

결과를 해석하면 다음과 같다.

요청 자체는 전부 성공했지만 응답 속도가 너무 느리다. 평균 4초, 최대 약 10초는 타임딜 서비스에서는 치명적인 수치다. DB 커넥션 풀을 관리하는 HikariCP 튜닝이 필요할 것 같다.

위처럼 OutOfSync + Degraded 상태가 떠서 로그를 확인해보기로 했다.

• OutOfSync: Git에 있는 설정과 실제 클러스터 상태가 다르다는 뜻
• Degraded: 배포된 애플리케이션이 정상 동작하지 않는다는 뜻

로그 확인

kubectl describe application pposiraegi -n argocd

로그에서 눈에 띄는 내용은 다음과 같았다.

external-secrets.io/ClusterSecretStore CRD가 없음
external-secrets.io/ExternalSecret CRD가 없음

ClusterSecretStore와 ExternalSecret CRD가 없다는 에러였다.

CRD(Custom Resource Definition)란 Kubernetes에 기본으로 없는 리소스 타입을 사용자가 직접 정의해서 추가하는 것이다. ESO를 설치하면 이 CRD들이 함께 등록된다.

원인은 이전 bootstrap 스크립트 실행 중 Loki 설치 단계에서 Windows 환경 문제로 오류가 발생했고, 그 이후 단계인 ESO(External Secrets Operator) 설치까지 진행되지 못했기 때문이었다. ESO는 AWS Secrets Manager 같은 외부 시크릿 저장소의 값을 Kubernetes Secret으로 자동으로 동기화해주는 도구다.

따라서 ESO만 따로 설치해주기로 했다.

ESO 따로 설치

./scripts/bootstrap-platform.sh --from eso

ESO 설치는 완료됐는데 여전히 OutOfSync 상태였다. Pod 상태를 확인해봤다.

waypoint만 떠 있고 나머지 서비스들이 올라오지 않은 상태였다. ArgoCD가 자동으로 sync를 하지 못하고 있어서 강제로 sync를 실행해보기로 했다.

ArgoCD sync 강제 실행

kubectl -n argocd exec -it $(kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o jsonpath='{.items[0].metadata.name}') -- argocd app sync pposiraegi --insecure --server argocd-server:80

ArgoCD CLI를 사용하려면 먼저 로그인이 필요하다고 떴다. 초기 admin 비밀번호를 확인한 뒤, port-forward로 ArgoCD 서버에 접근해서 로그인했다.

# 초기 admin 비밀번호 확인
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# port-forward 후 로그인
kubectl port-forward svc/argocd-server -n argocd 8080:80 &
sleep 3
kubectl -n argocd exec -it $(kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o jsonpath='{.items[0].metadata.name}') -- argocd login localhost:8080 --insecure --username admin --password [위에서 확인한 비밀번호]

로그인 성공. 이제 sync를 다시 실행했다.

kubectl -n argocd exec -it $(kubectl get pods -n argocd -l app.kubernetes.io/name=argocd-server -o jsonpath='{.items[0].metadata.name}') -- argocd app sync pposiraegi --insecure --server localhost:8080

sync가 정상적으로 진행되는 것을 확인했다. 이제 production 네임스페이스의 Pod 상태를 확인해봤다.

production Pod 확인

kubectl get pods -n production

모든 서비스의 Pod가 정상적으로 올라왔다. 이제 실제 서비스에 접속해봤다.

서비스 확인

pposiraegi.cloud에 정상적으로 접속되는 것을 확인했다. 길고 긴 삽질이 드디어 끝났다.

마무리 정리

팀원은 MacOS 환경이라 bootstrap 스크립트가 한 번에 실행됐지만, Windows 환경에서는 여러 문제가 연달아 발생했다.

• Git Bash에서 sudo 권한 없음 → helm 수동 설치
• helm 실행 경로 문제 → PATH 직접 설정
• Windows에 /proc 경로가 없음 → Loki 설치 실패
• kubectl이 aws CLI 경로를 인식하지 못함 → 심볼릭 링크 + kubeconfig 수동 수정
• ESO 미설치로 인한 CRD 누락 → ESO 단독 설치

같은 스크립트라도 OS 환경에 따라 전혀 다르게 동작할 수 있다는 걸 몸소 경험했다. 다음에 스크립트를 작성할 때는 OS 환경 분기 처리를 꼭 고려해야겠다고 느꼈다.

PowerShell 및 VS Code에서 실행 불가

처음에는 VS Code 터미널에서 그냥 실행하려 했다.

./scripts/bootstrap-platform.sh

당연히 실패했다. .sh 파일은 Linux/Mac 환경의 bash 스크립트이기 때문에, Windows의 PowerShell이나 VS Code 기본 터미널에서는 실행할 수 없다. bash를 실행할 수 있는 환경이 필요했다.

Git Bash 설치 + helm 설치

https://git-scm.com/download/win 에서 Git을 설치하면 Git Bash가 함께 설치된다. Git Bash는 Windows에서 bash 명령어를 쓸 수 있게 해주는 터미널 환경이다.

설치 후 Git Bash를 열고 다시 시도했다.

cd /c/pposiraegi-ecommerce
aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm
./scripts/bootstrap-platform.sh

이번엔 helm이 설치되어 있지 않다는 오류가 떴다.

[ERROR] helm 미설치

helm은 Kubernetes 패키지 매니저로, 차트(chart)라는 단위로 애플리케이션을 클러스터에 쉽게 배포할 수 있게 해준다. bootstrap 스크립트 내부에서 helm을 사용하기 때문에 반드시 설치가 필요했다.

Linux라면 sudo 명령어로 간단히 설치할 수 있지만, Git Bash 환경에서는 sudo 권한이 없어서 수동으로 다운받아 설치했다.

curl -L https://get.helm.sh/helm-v3.16.0-windows-amd64.zip -o helm.zip
unzip helm.zip
mv windows-amd64/helm.exe ./helm.exe
export PATH=$PATH:/c/pposiraegi-ecommerce

EKS 인증 문제

helm까지 설치하고 다시 실행했더니 이번엔 EKS 인증 오류가 떴다.

kubectl get nodes도 동일한 오류가 발생했다. aws eks get-token은 정상적으로 토큰을 반환하는데, kubectl이 이를 제대로 활용하지 못하는 상황이었다.

kubeconfig를 확인해보니 command: aws로 설정되어 있었는데, Git Bash 환경에서 aws CLI의 경로를 제대로 찾지 못하는 것이 원인이었다.

kubeconfig란? kubectl이 어떤 클러스터에 어떻게 접속할지 정의해둔 설정 파일이다. 보통 ~/.kube/config 경로에 위치한다.

kubeconfig 초기화 및 경로 문제 해결

전체 경로로 바꿔봤지만 경로에 공백이 포함되어 있어 또 실패했다. kubeconfig를 완전히 초기화하고 다시 시도했다.

rm ~/.kube/config
aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm
kubectl get nodes

여전히 안 됐다. kubeconfig 내용을 직접 확인해봤다.

command: aws 부분이 문제였다. aws CLI의 전체 경로로 바꿔야 하는데, Windows 특성상 경로에 공백이 포함되어 있어(C:\Program Files\...) 그대로 쓸 수가 없었다.

먼저 aws CLI의 실제 경로를 확인했다.

which aws

공백 문제를 우회하기 위해 심볼릭 링크를 만들기로 했다.

심볼릭 링크 생성

심볼릭 링크란 특정 파일이나 경로를 가리키는 바로가기 파일이다. 공백 없는 경로에 링크를 걸어두면 경로 문제를 우회할 수 있다.

ln -s "/c/Program Files/Amazon/AWSCLIV2/aws.exe" ~/aws.exe
sed -i 's|command: aws|command: /c/Users/gkthf/aws.exe|g' ~/.kube/config
kubectl get nodes

kubectl이 Windows 네이티브 바이너리라 Windows 경로 형식으로 바꿔서 다시 시도했다.

sed -i 's|command: /c/Users/gkthf/aws.exe|command: C:\\Program Files\\Amazon\\AWSCLIV2\\aws.exe|g' ~/.kube/config
kubectl get nodes

경로는 이제 제대로 찾는데, 이번엔 인증 문제가 또 떴다. kubeconfig 상태를 다시 확인했다.

cat ~/.kube/config | grep "command:"

경로는 맞는데 AWS_PROFILE 환경변수가 제대로 전달되지 않는 것 같아서, kubeconfig에 profile 설정이 있는지 확인했다.

cat ~/.kube/config | grep -A3 "env:"

profile은 존재했다. 그렇다면 AWS 자체 권한 문제일 수 있겠다 싶어 AWS 콘솔에 접속해서 확인해봤다.

IAM 사용자 목록을 보니 nahyung과 jihoon은 있는데 terraform-user가 없었다. kubeconfig에는 terraform-user 프로파일로 인증하도록 설정되어 있었으니 당연히 권한 오류가 날 수밖에 없었다.

terraform-user를 IAM에 생성한 뒤 다시 kubectl get nodes를 실행했다.

권한 할당

연결은 됐는데 이번엔 권한이 없다는 오류가 떴다. EKS는 IAM 사용자가 존재하더라도 클러스터 내부에 별도로 접근 권한을 부여해야 한다.

AWS 콘솔에서 다음 순서로 권한을 추가했다.

EKS → 해당 클러스터 → Access entries → terraform-user 선택 → Add access policy → AmazonEKSClusterAdminPolicy 추가

추가 완료 후 다시 실행했다.

kubectl get nodes

노드 목록이 정상적으로 출력됐다.

bootstrap 실행

경로 문제와 권한 문제가 모두 해결되어 드디어 bootstrap 스크립트를 실행할 수 있었다.

export PATH=$PATH:/c/pposiraegi-ecommerce
helm version
./scripts/bootstrap-platform.sh

bootstrap이 정상적으로 실행되며 ArgoCD, Karpenter, Istio 등 플랫폼 컴포넌트들이 클러스터에 설치되기 시작했다. 삽질이 길었지만 결국 해결됐다!

"production" not found 에러

이 에러는 production 네임스페이스가 존재하지 않아 발생하는 오류다. 원인을 파악해보니, terraform apply만 완료된 상태에서 아직 부트스트랩을 실행하지 않았기 때문에 발생하는 문제로 보였다. 기존 워크플로우에는 ECR에 이미지가 푸시된 이후 kubectl rollout restart를 실행하는 단계가 있었는데, ArgoCD가 자동으로 Sync를 수행하므로 해당 스텝은 사실상 불필요했다. 따라서 deploy-all.yml에서 아래 구간을 제거했다.

- name: Update kubeconfig
        run: aws eks update-kubeconfig --region ${{ env.AWS_REGION }} --name ${{ env.EKS_CLUSTER }}

      - name: Rollout restart (ArgoCD sync fallback)
        run: |
          kubectl rollout restart deployment/${{ matrix.service }} -n production

그런 다음 자동으로 Actions가 실행되기 때문에 기다려주었다.

수정 후 GitHub Actions가 자동으로 트리거되었고, 결과는 성공이었다.

처음에 깃허브 argocd가 안되어서 왜 그런가 봤더니

조직 레벨에서 외부 액션 사용이 막혀있어서 pnpm/action-setup@v3 같은 액션을 못 쓰는 문제가 생겼다. 이거를 프로젝트 레포에서 보니 변경이 막혀있어서

조직 Settings에서 "Allow all actions" 으로 변경해서 해결하였다.

terraform.tfvars가 .gitignore에 막혀서 변수 못 읽는 문제

보안상 tfvars 파일은 git에 올리지 않는데, GitHub Actions는 로컬 파일을 못 읽는 문제도 발생했다. 이는 CI 실행 시 GitHub Secrets에서 값을 주입해서 tfvars를 동적으로 생성하는 방식으로 해결하였다.

DockerFile 못찾는 오류

이렇게 apply까진 했는데 오류가 떴다. 에러를 확인해보니 DockerFIle을 못찾는 오류이다.

워크플로우에서는 working-directory: ./backend 로 설정했는데 실제 Dockerfile 위치가 다른것이다.

이렇게 백엔드 경로에 DockerFile이 없어서,

deploy-all.yml에서

      - name: Build, tag, and push image to Amazon ECR
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: pposiraegi-${{ matrix.service }}
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build --build-arg MODULE_NAME=${{ matrix.service }} -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG -t $ECR_REGISTRY/$ECR_REPOSITORY:latest .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest

working-directory: ./backend 이 줄을 삭제해준다.

그리고나서 다시 Actions를 실행해본다.

프론트엔드 오류

패키지 이름 오류

이번에는 프론트엔드쪽이 오류가 떴다.

프론트엔드 패키지 이름이 frontend가 아닌 것이다.

Get-Content해서 보니 timedeal-front라고 뜬다.

따라서 deploy-all.yml에서 패키지이름을 timedeal-front로 바꿔준다 (json을 frontend로 바꾸는게 낫지 않나 싶었는데 다른곳에서 참조할 경우가 있기 때문에 json에 맞추어서 depoly-all 파일을 바꿔준다.)

##기존
      - name: Build Frontend
        run: pnpm turbo run build --filter=frontend
##바꾼 코드
      - name: Build Frontend
        run: pnpm turbo run build --filter=timedeal-front

이렇게 코드를 바꿔준다.

ESLint 오류로 빌드 실패

이렇게 오류가 또 생겼는데 찾아보니, React useEffect missing dependencies, 미사용 변수 선언 등 ESLint 규칙 위반으로 빌드 실패한 것이었다.

프론트엔드도 내 담당이기 때문에 코드를 직접 수정해준다.

Run pnpm turbo run build --filter=timedeal-front

Attention:
Turborepo now collects completely anonymous telemetry regarding usage.
This information is used to shape the Turborepo roadmap and prioritize features.
You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
https://turborepo.dev/docs/telemetry


   • Packages in scope: timedeal-front
   • Running build in 1 packages
   • Remote caching disabled

timedeal-front:build
cache miss, executing b851ac8de420a9b8

> timedeal-front@0.1.0 build /home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend
> react-scripts build

Creating an optimized production build...

Treating warnings as errors because process.env.CI = true.
Most CI servers set it automatically.

Failed to compile.

[eslint] 
src/api/auth.js
  Line 167:1:  Assign object to a variable before exporting as module default  import/no-anonymous-default-export

src/api/config.js
  Line 7:1:  Assign object to a variable before exporting as module default  import/no-anonymous-default-export

src/api/order.js
  Line 118:1:  Assign object to a variable before exporting as module default  import/no-anonymous-default-export

src/api/timedeal.js
  Line 182:1:  Assign object to a variable before exporting as module default  import/no-anonymous-default-export

src/pages/AddressManager.jsx
  Line 30:6:  React Hook useEffect has missing dependencies: 'navigate' and 'user'. Either include them or remove the dependency array  react-hooks/exhaustive-deps

src/pages/AdminPage.jsx
  Line 57:6:  React Hook useEffect has a missing dependency: 'fetchDeals'. Either include it or remove the dependency array  react-hooks/exhaustive-deps

src/pages/MyPage.jsx
  Line 24:6:    React Hook useEffect has missing dependencies: 'navigate' and 'user'. Either include them or remove the dependency array  react-hooks/exhaustive-deps
  Line 227:28:  'v' is assigned to itself                                                                                                 no-self-assign

src/pages/OrderResult.jsx
  Line 26:6:  React Hook useEffect has missing dependencies: 'fetchOrder' and 'order'. Either include them or remove the dependency array  react-hooks/exhaustive-deps

src/pages/TimeDealDetail.jsx
  Line 41:6:  React Hook useEffect has missing dependencies: 'fetchDeal', 'fetchRelatedDeals', and 'user'. Either include them or remove the dependency array  react-hooks/exhaustive-deps
  Line 47:6:  React Hook useEffect has a missing dependency: 'fetchDeal'. Either include it or remove the dependency array                                     react-hooks/exhaustive-deps

src/pages/TimeDealList.jsx
  Line 6:26:   'logout' is defined but never used            no-unused-vars
  Line 12:16:  'setUser' is assigned a value but never used  no-unused-vars

src/pages/WishList.jsx
  Line 18:6:  React Hook useEffect has a missing dependency: 'navigate'. Either include it or remove the dependency array  react-hooks/exhaustive-deps


 ELIFECYCLE  Command failed with exit code 1.
Error: timedeal-front#build: command (/home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend) /home/runner/setup-pnpm/node_modules/.bin/pnpm run build exited (1)
 ERROR  timedeal-front#build: command (/home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend) /home/runner/setup-pnpm/node_modules/.bin/pnpm run build exited (1)

 Tasks:    0 successful, 1 total
Cached:    0 cached, 1 total
  Time:    13.829s 
Failed:    timedeal-front#build

 ERROR  run failed: command  exited (1)
Error: Process completed with exit code 1.

일단 오류 로그는 이렇게 떴다.

• frontend/src/api/auth.js
• frontend/src/api/config.js
• frontend/src/api/order.js
• frontend/src/api/timedeal.js
• frontend/src/pages/AddressManager.jsx
• frontend/src/pages/AdminPage.jsx
• frontend/src/pages/MyPage.jsx
• frontend/src/pages/OrderResult.jsx
• frontend/src/pages/TimeDealDetail.jsx
• frontend/src/pages/TimeDealList.jsx
• frontend/src/pages/WishList.jsx 이렇게, 고쳐야할 파일이 11개나 되기 때문에 아찔했다. 그래도 임시방편으로 deploy-all에서 CI: false 하는것보단 근본적으로 고치는게 내 성격에 맞기 때문에 고쳐준다.

일단 코드가 frontend/src/api/auth.js같은 경우에는

##중략
// 401 인터셉터: 토큰 만료 시 자동 로그아웃 + 로그인 페이지 이동
axios.interceptors.response.use(
  res => res,
  err => {
    if (err.response?.status === 401) {
      localStorage.removeItem('accessToken');
      localStorage.removeItem('refreshToken');
      localStorage.removeItem('user');
      sessionStorage.removeItem('user');
      // 현재 페이지가 /login이 아닐 때만 리다이렉트
      if (!window.location.pathname.startsWith('/login')) {
        window.location.href = '/login?expired=1';
      }
    }
    return Promise.reject(err);
  }
);

export default { login, register, logout, getCurrentUser, saveAddress, getAddress };

이렇게 되어있는데 맨 마지막줄을

const authAPI = { login, register, logout, getCurrentUser, saveAddress, getAddress };
export default authAPI;

이런식으로 고쳐준다. (거의 모든 파일이 저렇게 되어있어서 저런식으로 고쳐준다.)

또는 useEffect에서 발생하는 오류가 있는데, 이는 dependency array 문제다. React의 useEffect는 두 번째 인자로 dependency array를 받는데, useEffect 내부에서 사용하는 변수나 함수가 dependency array에 없으면 ESLint가 경고를 띄운다.

예를 들어 AddressManager.jsx의 경우

jsuseEffect(() => {
    if (!user) { navigate('/login'); return; }
    ...
}, []); // ← navigate, user를 사용하는데 dependency array가 비어있음

이런 경우 navigate와 user를 dependency array에 추가해줘야 한다.

jsuseEffect(() => {
    if (!user) { navigate('/login'); return; }
    ...
}, [navigate, user]); // ← 추가

단, TimeDealDetail.jsx처럼 fetchDeal, fetchRelatedDeals 같은 함수를 dependency에 넣으면 무한루프가 발생할 수 있다. 이런 경우 해당 함수를 useCallback으로 감싸서 함수 참조가 변경되지 않도록 처리해준다.

그리고나서 Actions가 잘 돌아가는지 확인한다.

fetchDeals, fetchOrder를 useCallback으로 감싸 무한루프 방지

Actions를 돌렸더니 이러한 오류가 떴다.

Run pnpm turbo run build --filter=timedeal-front

Attention:
Turborepo now collects completely anonymous telemetry regarding usage.
This information is used to shape the Turborepo roadmap and prioritize features.
You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
https://turborepo.dev/docs/telemetry


   • Packages in scope: timedeal-front
   • Running build in 1 packages
   • Remote caching disabled

timedeal-front:build
cache miss, executing 381ed73731ab9079

> timedeal-front@0.1.0 build /home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend
> react-scripts build

Creating an optimized production build...

Treating warnings as errors because process.env.CI = true.
Most CI servers set it automatically.

Failed to compile.

[eslint] 
src/pages/AdminPage.jsx
  Line 57:7:  'fetchDeals' was used before it was defined                                                                                                                                             no-use-before-define
  Line 59:9:  The 'fetchDeals' function makes the dependencies of useEffect Hook (at line 57) change on every render. To fix this, wrap the definition of 'fetchDeals' in its own useCallback() Hook  react-hooks/exhaustive-deps

src/pages/OrderResult.jsx
  Line 26:6:  React Hook useEffect has a missing dependency: 'fetchOrder'. Either include it or remove the dependency array  react-hooks/exhaustive-deps
Error: timedeal-front#build: command (/home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend) /home/runner/setup-pnpm/node_modules/.bin/pnpm run build exited (1)
 ERROR  timedeal-front#build: command (/home/runner/work/pposiraegi-ecommerce/pposiraegi-ecommerce/frontend) /home/runner/setup-pnpm/node_modules/.bin/pnpm run build exited (1)


 ELIFECYCLE  Command failed with exit code 1.

 Tasks:    0 successful, 1 total
Cached:    0 cached, 1 total
  Time:    13.493s 
Failed:    timedeal-front#build

 ERROR  run failed: command  exited (1)
Error: Process completed with exit code 1.

아까보다는 나아졌다. 이제는 AdminPage.jsx랑 OrderResult.jsx만 에러가 뜨고 있다.

AdminPage.jsx - import에 useCallback 추가하고 fetchDeals를 useCallback으로 감싸고 useEffect 위로 올려 수정해준다.

OrderResult.jsx - import에 useCallback 추가하고 fetchOrder를 useCallback으로 감싸 수정해준다.

그리고 다시 Actions를 실행해준다.

fetchDeals, fetchOrder 함수 누락으로 인한 not defined 오류 수정

방금 고친 AdminPage랑 OrderResult에서 여러가지를 수정하며, 쓰지 않는 함수를 삭제했는데 잘못 삭제하여 함수를 찾지 못한다고 에러가 떠서 다시 추가해준다.

그리고 또 Actions를 기대해준다.

프론트엔드 마침내 성공

마침내 프론트엔드 빌드가 성공했다. 길고 길었던 ESLint 오류와의 싸움이 끝났다.

이제 4개의 백엔드와의 긴 싸움이 남았다.

저번 포스팅에서 ArgoCD 연결까지는 성공했는데, production Pod를 띄우는 과정에서 CrashLoopBackOff 오류가 발생했다.

이번 포스팅에서는 원인을 추적하고 해결하는 과정을 기록한다.

CrashLoopBackOff란?
컨테이너가 시작됐다가 바로 죽는 걸 반복하는 상태다.
쿠버네티스가 "계속 죽으니까 잠깐 기다렸다가 다시 시작할게" 하면서 점점 재시작 간격을 늘린다.
보통 앱 설정 오류, DB 연결 실패, 환경변수 누락 등이 원인이다.

1. EKS 연결

먼저 로컬에서 EKS 클러스터에 접근할 수 있도록 kubeconfig를 설정한다.

# kubeconfig 연결
aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm

# 노드 상태 확인
kubectl get nodes

노드가 Ready 상태로 뜨면 클러스터 연결은 정상이다.

노드(Node)란?
쿠버네티스에서 실제로 컨테이너가 실행되는 서버(가상머신)다.
EKS에서는 EC2 인스턴스가 노드 역할을 한다.

2. 어떤 Pod가 죽었는지 확인

kubectl get pods -n production

아무것도 뜨지 않았다.

-n production이란?
-n은 네임스페이스(namespace)를 지정하는 옵션이다.
쿠버네티스는 리소스를 네임스페이스라는 공간으로 분리해서 관리한다.
production은 실제 서비스가 올라가는 공간이다.

production 네임스페이스에 Pod가 하나도 없다는 건, ArgoCD가 아직 sync를 하지 않은 것이다.
즉, GitHub 레포에 있는 매니페스트 파일들이 클러스터에 아직 반영되지 않은 상태라는 뜻이다.

ArgoCD부터 다시 설치하고 연결해야 한다.

3. ArgoCD 재설치

# argocd 네임스페이스 생성
kubectl create namespace argocd

# 공식 매니페스트 적용
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

created 메시지들이 쭉 뜨면 설치가 진행 중인 것이다.

설치 완료 후 Pod 상태를 확인한다:

kubectl get pods -n argocd

모든 Pod의 STATUS가 Running으로 바뀌면 다음 단계로 넘어간다.
처음엔 ContainerCreating이나 Pending으로 뜨는 게 정상이니 잠깐 기다리면 된다.

4. ArgoCD UI 접속

ArgoCD는 웹 UI를 제공한다. 포트 포워딩으로 로컬에서 접속한다.

kubectl port-forward svc/argocd-server -n argocd 8080:443

포트 포워딩이란?
클러스터 내부 서비스를 외부에 노출하지 않고, 내 PC에서만 접근할 수 있도록 통로를 만드는 것이다.
위 명령어는 "내 PC의 8080번 포트로 들어오는 요청을 ArgoCD 서버의 443 포트로 전달해줘"라는 뜻이다.

브라우저에서 https://localhost:8080 접속 후 로그인한다.

초기 비밀번호 확인 (PowerShell):

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }

• 아이디: admin
• 비밀번호: 위 명령어 출력값

⚠️ 브라우저에서 "안전하지 않은 연결" 경고가 뜨면 고급 → 계속 진행을 누르면 된다.
자체 서명 인증서라서 뜨는 경고로, 로컬 개발 환경에서는 정상이다.

5. namespace 및 Secret 생성

ArgoCD가 배포할 production 네임스페이스와 DB/Redis 접속 정보를 미리 만들어줘야 한다.
이 작업을 먼저 해두지 않으면 Pod가 뜨다가 환경변수를 못 찾아서 바로 죽는다.

# namespace, configmap 먼저 생성
kubectl apply -f kubernetes/base/namespace.yaml
kubectl apply -f kubernetes/base/configmap.yaml

RDS, Redis 엔드포인트를 확인한다:

terraform output rds_endpoint
terraform output elasticache_endpoint

확인한 엔드포인트로 Secret을 생성한다:

kubectl create secret generic app-secret \
  --namespace=production \
  --from-literal=DB_HOST=RDS엔드포인트 \
  --from-literal=DB_USERNAME=pposiraegi \
  --from-literal=DB_PASSWORD=DB비밀번호 \
  --from-literal=REDIS_HOST=Redis엔드포인트 \
  --from-literal=JWT_SECRET=JWT시크릿

Secret이란?
비밀번호, API 키처럼 코드에 직접 넣으면 안 되는 민감한 값을 쿠버네티스 내부에서 안전하게 관리하는 리소스다.
--from-literal로 값을 넣으면 자동으로 base64로 인코딩되어 저장된다.
Pod에서는 환경변수 형태로 이 값을 꺼내 쓸 수 있다.

6. ArgoCD App 연결 및 Sync

kubectl apply -f argocd-app.yaml

터미널에서 직접 sync한다:

# argocd-server Pod 이름 먼저 확인
kubectl get pods -n argocd

# ArgoCD 서버에 로그인
kubectl -n argocd exec -it [argocd-server-Pod이름] -- \
  argocd login localhost:8080 --insecure --username admin --password [비밀번호]

# Sync 실행
kubectl -n argocd exec -it [argocd-server-Pod이름] -- \
  argocd app sync pposiraegi --insecure

exec -it란?
실행 중인 Pod 안으로 직접 들어가서 명령어를 실행하는 것이다.
마치 서버에 SSH로 접속해서 명령어를 치는 것과 같다.

7. Pod 상태 확인 및 로그 분석

kubectl get pods -n production

Pod들이 뜨기 시작하면 각 Pod의 로그를 확인한다:

# 현재 로그 확인
kubectl logs -n production [죽은Pod이름]

# 이미 죽은 컨테이너의 직전 로그 확인
kubectl logs -n production [죽은Pod이름] --previous

order-service Pod의 로그를 먼저 확인했다.

Connect timed out

원인 분석:

보안 그룹(Security Group)이란?
AWS에서 서버 간 트래픽을 허용/차단하는 방화벽 역할을 한다.
RDS의 보안 그룹에 EKS 노드가 포함되어 있지 않으면 아무리 올바른 주소로 접속해도 연결이 차단된다.

8. EKS 노드 보안 그룹을 동적으로 추가

EKS는 배포할 때마다 보안 그룹 ID가 바뀐다.
그래서 ID를 하드코딩하지 않고, Terraform이 자동으로 가져오도록 동적으로 연결했다.

왜 동적으로 해야 할까?
terraform apply를 할 때마다 EKS가 새 보안 그룹을 만든다.
매번 수동으로 ID를 복사해서 넣으면 실수가 생기고 유지보수가 어렵다.
Terraform 모듈끼리 연결해두면 항상 최신 ID를 자동으로 참조한다.

1) modules/security/variables.tf에 변수 추가

variable "eks_cluster_sg_id" {
  description = "EKS cluster security group ID"
  default     = ""
}

2) modules/security/main.tf 수정

RDS와 Redis 보안 그룹에 EKS 노드 접근 허용 규칙을 추가한다.

# RDS 보안 그룹 — PostgreSQL 5432 포트
ingress {
  from_port       = 5432
  to_port         = 5432
  protocol        = "tcp"
  security_groups = [var.eks_cluster_sg_id]
}

# Redis 보안 그룹 — Redis 6379 포트
ingress {
  from_port       = 6379
  to_port         = 6379
  protocol        = "tcp"
  security_groups = [var.eks_cluster_sg_id]
}

3) modules/eks/outputs.tf에 출력값 추가

EKS 모듈이 보안 그룹 ID를 외부로 내보낼 수 있도록 output을 추가한다.

output "cluster_security_group_id" {
  value = aws_eks_cluster.main.vpc_config[0].cluster_security_group_id
}

4) 루트 main.tf에서 모듈 간 연결

module "security" {
  source = "./modules/security"

  project_name      = var.project_name
  vpc_id            = module.networking.vpc_id
  eks_cluster_sg_id = module.eks.cluster_security_group_id  # EKS에서 자동으로 가져옴
}

이렇게 연결해두면 terraform apply를 할 때마다 EKS가 새로 만드는 보안 그룹 ID를 자동으로 참조한다.

수정 후 적용:

terraform apply -var-file="terraform.tfvars"

9. Terraform apply 후 ArgoCD 재sync

apply 후 ArgoCD 상태를 확인했는데 뭔가 이상해 보였다.

혹시 Secret이나 엔드포인트가 잘못됐나 싶어서 다시 확인했다.

Secret과 엔드포인트는 정상적으로 등록된 것을 확인했다. 그래서 다시 sync를 시도했다.

# ArgoCD 서버에 로그인
kubectl -n argocd exec -it argocd-server-78f5bb67d5-xt9g6 -- \
  argocd login localhost:8080 --insecure --username admin --password [패스워드]

# Sync 실행
kubectl -n argocd exec -it argocd-server-78f5bb67d5-xt9g6 -- \
  argocd app sync pposiraegi --insecure

각 명령어의 의미를 정리하면:

첫 번째 명령어 — ArgoCD 로그인

두 번째 명령어 — App Sync

10. 그런데 또 문제가 — kubeconfig와 RBAC

여기까지 했는데도 production Pod가 여전히 뜨지 않았다.

팀원과 공유하는 과정에서 원인이 두 가지 더 있다는 걸 알게 됐다.

원인 1 — kubeconfig가 예전 엔드포인트를 가리키고 있음

terraform apply를 다시 하면 EKS 클러스터가 재생성되면서 API 서버 엔드포인트 주소가 바뀐다.
그런데 로컬의 kubeconfig는 예전 주소를 그대로 들고 있기 때문에, kubectl 명령어가 존재하지 않는 클러스터에 계속 요청을 보내고 있던 것이다.
해결 방법은 간단하다. aws eks update-kubeconfig를 다시 실행해서 최신 엔드포인트로 갱신해주면 된다.

aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm

원인 2 — RBAC 권한 문제

RBAC(Role-Based Access Control)란?
쿠버네티스에서 "누가 무엇을 할 수 있는지" 권한을 관리하는 시스템이다.
ArgoCD가 production 네임스페이스에 Pod를 배포하려면 그에 맞는 권한이 부여되어 있어야 한다.
권한이 없으면 sync는 성공해도 실제 리소스가 생성되지 않거나 오류가 발생한다.

이 두 가지 문제가 복합적으로 작용해서 production Pod가 계속 뜨지 않았던 것이다.

마무리

이번 포스팅에서 겪은 문제들을 정리하면:

트러블슈팅을 하다 보면 문제 하나를 해결하면 또 다른 문제가 나오는 게 일상이다.
RBAC 권한 설정과 부트스트랩 스크립트 적용 과정은 다음 포스팅에서 이어서 정리할 예정이다. 😅

이번 포스팅은 ArgoCD Sync를 시도하다가 연속으로 두 가지 문제를 맞닥뜨린 트러블슈팅 기록이다.
결론부터 말하면 레포 이름 오타 → 폴더 경로 오류 → RDS 보안 그룹 차단 순서로 문제가 터졌고, 아직 완전히 해결 전 단계다.

사전 준비 — 엔드포인트 확인 및 리소스 생성

Sync 전에 RDS, ElastiCache 엔드포인트를 확인하고 쿠버네티스 리소스를 미리 만들어둔다.

# RDS, ElastiCache 엔드포인트 확인
terraform output rds_endpoint
terraform output elasticache_endpoint

# namespace, configmap 생성
kubectl apply -f kubernetes/base/namespace.yaml
kubectl apply -f kubernetes/base/configmap.yaml

# DB, Redis, JWT 정보를 Secret으로 등록
kubectl create secret generic app-secret \
  --namespace=production \
  --from-literal=DB_HOST=pposiraegi-db.c5wkmcaauwn2.ap-northeast-2.rds.amazonaws.com \
  --from-literal=DB_USERNAME=pposiraegi \
  --from-literal=DB_PASSWORD=DB비밀번호 \
  --from-literal=REDIS_HOST=pposiraegi-redis.qka9g8.0001.apn2.cache.amazonaws.com \
  --from-literal=JWT_SECRET=JWT시크릿

Secret이란?
비밀번호, API 키처럼 외부에 노출되면 안 되는 값을 쿠버네티스 안에서 안전하게 관리하는 리소스다.
--from-literal로 값을 직접 넣으면 자동으로 base64 인코딩되어 저장된다.

트러블슈팅 1 — ArgoCD Sync 실패 (레포/경로 문제)

Sync 시도

kubectl apply -f argocd-app.yaml

# UI에서 SYNC → SYNCHRONIZE 클릭 후 반응 없음
# 터미널로 직접 해결하기로 함

# ArgoCD 파드 확인
kubectl get pods -n argocd

# ArgoCD 서버에 직접 로그인
kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd login localhost:8080 --insecure --username admin --password NDiUuc1t8XJKmF2O

# 수동 Sync
kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd app sync pposiraegi --insecure

UI에서 Sync 버튼을 눌렀는데 아무 반응이 없어서, ArgoCD 서버 파드에 직접 exec로 들어가서 CLI로 진행했다.

문제 1 — feat/eks-migration 브랜치를 못 찾음

브랜치를 찾지 못한다는 에러가 발생했다. 하나씩 확인했다.

# 원격 브랜치 목록 확인
git branch -r

→ 브랜치는 실제로 존재함.

# 해당 브랜치에 커밋이 있는지 확인
git log --oneline origin/feat/eks-migration

→ 커밋도 있음.

# argocd-app.yaml 내용 확인
cat argocd-app.yaml

→ path 설정은 이상 없음.

# 실제 레포 이름 확인
git remote -v

원인 발견 — 레포 이름 오타

argocd-app.yaml의 repoURL을 올바른 주소로 수정 후 재적용했다.

kubectl apply -f argocd-app.yaml
kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd app sync pposiraegi --insecure

문제 2 — app path does not exist

레포 이름은 고쳤는데 이번엔 경로 문제가 발생했다.

원인

ArgoCD는 레포 루트에서 kubernetes/ 폴더를 찾는데,
실제 폴더 구조는 infrastructure/kubernetes/ 였다.

pposiraegi-ecommerce/
└── infrastructure/
    └── kubernetes/   ← 실제 위치

argocd-app.yaml의 path를 infrastructure/kubernetes로 수정 후 재적용했다.

kubectl apply -f argocd-app.yaml
kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd app sync pposiraegi --insecure

→ 연결 성공 🎉

트러블슈팅 2 — Pod CrashLoopBackOff (RDS 보안 그룹 차단)

다시 Sync 후 Pod 상태 확인

kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd app sync pposiraegi --insecure

→ successfully synced

그런데 Pod 상태를 확인하니 문제가 있었다.

kubectl get pods -n production

처음엔 Running처럼 보였는데...

→ CrashLoopBackOff 발생

CrashLoopBackOff란?
컨테이너가 시작됐다가 바로 죽는 걸 반복하는 상태다.
보통 앱 내부 에러, 설정 오류, 외부 서비스 연결 실패 등이 원인이다.

no more tasks 문제

Sync 중 no more tasks 에러도 함께 발생했다.

ArgoCD가 infrastructure/kubernetes/ 하위 폴더를 재귀적으로 탐색하지 못해서 production Pod를 찾지 못하는 문제였다.

해결 — directory.recurse: true 추가

argocd-app.yaml에 재귀 탐색 옵션을 추가했다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: pposiraegi
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/Goorm4I/pposiraegi-ecommerce
    targetRevision: feat/eks-migration
    path: infrastructure/kubernetes
    directory:
      recurse: true   # 하위 폴더까지 재귀적으로 탐색
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
    - CreateNamespace=true

kubectl apply -f argocd-app.yaml
kubectl -n argocd exec -it argocd-server-7648988dc6-zq7hn -- \
  argocd app sync pposiraegi --insecure

Pod는 뜨기 시작했지만... CrashLoopBackOff는 계속됐다.

로그로 원인 파악

kubectl logs -n production order-service-88547fbf4-vcl4k

Connect timed out

원인 — EKS 노드 → RDS 보안 그룹이 막혀있음

기존 RDS 보안 그룹 인바운드 규칙이 api_gateway_sg, internal_msa_sg만 허용하고 있었는데, EKS 노드는 다른 보안 그룹을 사용하고 있어서 접근이 차단된 상태였다.

해결 — EKS 노드 보안 그룹 ID 확인 후 RDS/Redis 보안 그룹에 추가

# EKS 클러스터 보안 그룹 ID 확인
aws eks describe-cluster \
  --name pposiraegi-cluster \
  --query "cluster.resourcesVpcConfig.clusterSecurityGroupId" \
  --output text \
  --profile goorm

→ sg-0aa36452edaf69dd9 확인

modules/security/main.tf에서 rds_sg와 redis_sg에 EKS 노드 보안 그룹을 추가했다.

rds_sg — PostgreSQL 5432 포트 허용 추가

resource "aws_security_group" "rds_sg" {
  vpc_id      = var.vpc_id
  name        = "${var.project_name}-rds-sg"
  description = "RDS PostgreSQL security group"

  ingress {
    from_port       = 5432
    to_port         = 5432
    protocol        = "tcp"
    security_groups = [aws_security_group.api_gateway_sg.id, aws_security_group.internal_msa_sg.id]
  }

  # EKS 노드 접근 허용 추가
  ingress {
    from_port       = 5432
    to_port         = 5432
    protocol        = "tcp"
    security_groups = ["sg-0aa36452edaf69dd9"]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }

  tags = { Name = "${var.project_name}-rds-sg" }
}

redis_sg — Redis 6379 포트 허용 추가

# EKS 노드 접근 허용 추가
ingress {
  from_port       = 6379
  to_port         = 6379
  protocol        = "tcp"
  security_groups = ["sg-0aa36452edaf69dd9"]
}

# Terraform으로 보안 그룹 변경 적용
terraform apply -var-file="terraform.tfvars"

정리

Terraform 적용 후 Pod가 정상적으로 뜨는지는 다음 포스팅에서 이어서 정리할 예정이다.

이번 포스팅에서는 AWS EKS 클러스터에 ArgoCD를 설치하고, GitHub 레포지토리와 연동해서 자동 배포까지 설정하는 과정을 정리했다.

ArgoCD란?
Kubernetes 환경에서 GitOps 방식의 배포를 도와주는 툴이다.
쉽게 말하면, GitHub에 코드를 올리면 ArgoCD가 자동으로 감지해서 클러스터에 배포해주는 자동화 배포 도구다.

1. kubeconfig 연결

먼저 로컬 환경에서 EKS 클러스터에 접근할 수 있도록 kubeconfig를 설정해야 한다.
kubectl 명령어가 어느 클러스터를 바라볼지 알려주는 작업이라고 생각하면 된다.

# kubeconfig 연결
aws eks update-kubeconfig --region ap-northeast-2 --name pposiraegi-cluster --profile goorm

# 클러스터 연결 확인
kubectl get nodes

• --region: 클러스터가 위치한 AWS 리전
• --name: EKS 클러스터 이름
• --profile: AWS CLI에 등록된 프로파일 이름

kubectl get nodes로 노드 목록이 출력되면 연결 성공이다.

2. ArgoCD 설치

ArgoCD를 위한 네임스페이스를 먼저 만들고, 공식 매니페스트를 적용해서 설치한다.

# ArgoCD 전용 네임스페이스 생성
kubectl create namespace argocd

# ArgoCD 공식 매니페스트 적용
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 설치 완료 확인 (모든 Pod가 Running 상태여야 함)
kubectl get pods -n argocd

네임스페이스(namespace)란?
쿠버네티스 안에서 리소스를 논리적으로 분리하는 공간이다.
ArgoCD 관련 리소스만 모아두기 위해 별도 네임스페이스를 만든다.

설치 후 kubectl get pods -n argocd를 실행했을 때, 모든 Pod의 STATUS가 Running으로 바뀌면 설치 완료다. (처음엔 ContainerCreating으로 뜨는 게 정상이니 잠깐 기다리자.)

3. ArgoCD UI 접속

ArgoCD는 웹 UI를 제공한다. 외부에 바로 노출하지 않고 포트 포워딩으로 로컬에서 접속할 수 있다.

# 로컬 8080 포트 → ArgoCD 서버 443 포트로 포워딩
kubectl port-forward svc/argocd-server -n argocd 8080:443

포트 포워딩이란?
클러스터 내부 서비스를 외부로 노출하지 않고, 내 로컬 PC에서만 접근할 수 있도록 터널을 뚫어주는 것이다.

이 명령어를 실행한 상태로 브라우저에서 https://localhost:8080 에 접속하면 ArgoCD 로그인 화면이 나온다.

⚠️ 브라우저에서 "안전하지 않은 연결"이라고 경고가 뜰 수 있는데, 자체 서명 인증서라서 그렇다. 고급 → 계속 진행을 누르면 된다.

4. 초기 비밀번호 확인

초기 관리자 계정은 admin이고, 비밀번호는 쿠버네티스 시크릿에 저장되어 있다.

Linux / macOS:

kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d

Windows (PowerShell):

kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | ForEach-Object { [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String($_)) }

출력된 값이 초기 비밀번호다. 로그인 후에는 보안을 위해 비밀번호를 변경하는 걸 추천한다.

5. ArgoCD App 설정 (GitOps 연동)

이제 핵심이다. ArgoCD가 GitHub 레포지토리를 감시하고 자동으로 배포하도록 Application 리소스를 생성한다.

kubectl apply -f - <<EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: pposiraegi
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/Goorm4I/pposiraegi-ecommerce-msa  # 감시할 GitHub 레포
    targetRevision: feat/eks-migration                             # 대상 브랜치
    path: kubernetes                                               # 매니페스트 파일 경로
  destination:
    server: https://kubernetes.default.svc
    namespace: production                                          # 배포할 네임스페이스
  syncPolicy:
    automated:
      prune: true      # 레포에서 삭제된 리소스는 클러스터에서도 삭제
      selfHeal: true   # 클러스터가 레포와 달라지면 자동으로 복구
    syncOptions:
    - CreateNamespace=true  # production 네임스페이스 없으면 자동 생성
EOF

yaml 파일로 따로 저장했다면 이렇게 적용할 수도 있다:

kubectl apply -f argocd-app.yaml

각 설정의 의미:

6. 상태 확인

ArgoCD UI에서 App이 정상적으로 생성된 것을 확인할 수 있다.

Synced + Healthy 상태가 뜨면 GitHub 레포와 클러스터가 정상적으로 연동된 것이다. 이제 해당 브랜치에 커밋을 푸시하면 ArgoCD가 자동으로 감지해서 클러스터에 반영해준다.

마무리

GitOps를 도입하면 배포 이력이 GitHub 커밋 히스토리에 그대로 남고, 문제가 생겼을 때 revert만으로 롤백이 가능해서 운영이 훨씬 편해진다. 처음 설정이 좀 번거롭지만 한 번 해두면 그 이후엔 정말 편하다!

팀원이 tfstate s3 버킷을 지정하면서 오류가 생겨서 이거때문에 terraform apply가 안되는 오류가 발생했다.

팀원이 보내준 사유는 다음과 같다

현재 pposiraegi-ecommerce repo에서 Terraform/EKS 접근 문제가 있습니다.
중요: 파일 수정하지 말고 먼저 진단만 해주세요. terraform apply 금지. terraform import 금지. destructive command 금지.
현재 확인된 상태: AWS_PROFILE=goorm 계정: 779846782353 EKS cluster: pposiraegi-cluster, ACTIVE, version 1.32 NodeGroup: pposiraegi-node-group, ACTIVE, t3.medium 2대 healthy Terraform backend: bucket = pposiraegi-tf-state-779846782353 key = ecommerce/terraform.tfstate 해당 backend key에 state object가 없는 것으로 보임 terraform plan 실행 시 기존 리소스를 인식하지 못하고 86 to add 따라서 현재 apply하면 중복 생성/충돌 위험 kubectl은 kubeconfig 생성은 되지만 Kubernetes API 접근 실패:"the server has asked for the client to provide credentials" EKS authenticationMode는 CONFIG_MAP 현재 IAM user arn:aws:iam::779846782353:user/jihoon이 aws-auth에 매핑되지 않은 것으로 추정
해야 할 일: 실제 Terraform state 위치를 찾기 backend.tf와 실제 state 위치 불일치 여부 확인 state 유실이면 import 대상 목록 정리만 하기 aws-auth 또는 EKS access 권한 복구 방안 제안 팀원이 공통으로 사용할 AWS_PROFILE/backend/tfvars 절차 문서화 제안

진단하기

이거에 대한 해결방법은 사실 아직까지 잘 모르겠다. 차근차근 진단해보기로 했다.

1. Terraform state 위치 찾기

# S3 버킷 목록 전체 확인
aws s3 ls --profile goorm

# 팀원이 말한 버킷 확인
aws s3 ls s3://pposiraegi-tf-state-779846782353 --profile goorm

# 버킷 안에 뭐가 있는지
aws s3 ls s3://pposiraegi-tf-state-779846782353 --recursive --profile goorm

이렇게 가장 최근에 만든 프로필인 pposiraegi-tf-state-779846782353에는 아무것도 없고

pposiraegi-tfstate-779846782353에 infrastructure/terraform.tfstate 파일이 들어있는 것을 확인할 수 있다.

2. 원인 파악

S3 버킷이 두 개 존재하는 것을 확인했다.

팀원이 설정한 backend 버킷 이름은 pposiraegi-tf-state-779846782353이었는데, 실제 state 파일은 pposiraegi-tfstate-779846782353에 있었다. 버킷 이름이 미묘하게 달랐던 것이 원인이었다.

팀원 backend 설정: bucket = "pposiraegi-tf-state-779846782353" ← 없는 버킷 (tf-state) key = "ecommerce/terraform.tfstate" ← 경로도 다름 실제 state 위치: bucket = "pposiraegi-tfstate-779846782353" ← 진짜 버킷 (tfstate) key = "infrastructure/terraform.tfstate" ← 실제 경로

3. backend.tf 파일 없는 것 확인

팀원 backend 설정: bucket = "pposiraegi-tf-state-779846782353" ← 없는 버킷 (tf-state) key = "ecommerce/terraform.tfstate" ← 경로도 다름 실제 state 위치: bucket = "pposiraegi-tfstate-779846782353" ← 진짜 버킷 (tfstate) key = "infrastructure/terraform.tfstate" ← 실제 경로

따라서, 중복생성과 충돌이 발생할 위험이 있었다.

4. 해결 방법: backend.tf 생성

infrastructure/backend.tf 파일을 새로 만들어서 S3 backend를 명시적으로 설정했다.

terraform {
  backend "s3" {
    bucket  = "pposiraegi-tfstate-779846782353"
    key     = "infrastructure/terraform.tfstate"
    region  = "ap-northeast-2"
    profile = "goorm"
  }
}

이렇게 하면 뭐가 좋아지냐면:

5. terraform init 재실행

backend.tf 생성 후 terraform init을 다시 실행해서 S3 backend를 인식시켜줬다.

terraform init -reconfigure

-reconfigure 옵션은 기존 backend 설정을 무시하고 새로운 backend로 다시 초기화하는 옵션이다.

이후 terraform plan을 실행하면 기존 리소스를 정상적으로 인식하고 No changes 또는 실제 변경사항만 표시되어야 한다.

정리

이번 문제의 핵심은 두 가지였다.

1. 버킷 이름 불일치: 팀원이 설정한 버킷 이름과 실제 state가 있는 버킷 이름이 달랐다.
2. backend.tf 파일 부재: 팀 전체가 공유해야 하는 backend 설정이 코드로 관리되지 않고 있었다.

앞으로는 backend.tf를 Git에 포함해서 팀원 모두가 동일한 S3 backend를 바라보도록 관리하도록 변경하였다.

본 콘텐츠는 구름 서포터즈 활동으로 지원을 받아 작성된 교육생의 실제 경험 후기입니다.

이전 게시물에서 프로젝트를 시작했을 때 포스팅을 남겨놓았다. 그때는 기획 수준이었는데, 지금은 그때와는 다른 고민들을 하기 시작했다. CI/CD 파이프라인 구성이라든지, 자동 배포 전략은 어떻게 할 것인지 등등. 아직은 반 수동 배포인 상황이지만, 앱이 잘 돌아가는 상태로는 만들었다. 일단 이전 게시물과 가장 크게 달라진 점은 인프라 구성도인 것 같다.

기존과 가장 달라진 점

기존엔 bastion 서버를 두어서 private 서브넷에 있는 자원들에 접근하게 했는데, 지금은 SSM 서비스를 이용해 콘솔에 로그인하면 바로 EC2에 접근할 수 있도록 변경했다. (현재 이 아키텍처도 수정해야 할 부분이 많다는 건 인지하고 있다. 백엔드 EC2를 private에 두어야 한다는 점 등.) 이 아래는 프로젝트 발표 때 사용했던 PPT다. 우리가 고려한 백엔드 엣지케이스라든가, 바뀐 인프라 아키텍처를 확인해볼 수 있다.

백엔드 엣지케이스 고려 및 바뀐 인프라 전략

bastion에서 SSM으로 전환한 이유

프로젝트 발표 중에 가장 첫번째로 받은 질문이 왜 bastion을 두지 않았느냐 인 것 같다. ssm으로 전환 시 가장 팀원들이랑 많이 얘기했던 부분들이기도 하고. 왜 bastion에서 ssm으로 전환하였냐면 다음과 같은 이유들 때문이다.

• 보안 측면에서 더 유리하다. bastion을 운영하려면 SSH 포트(22번)를 외부에 열어둬야 하는데, 이 자체가 공격 표면이 된다. SSM은 인바운드 포트를 아예 열 필요가 없고, IAM 기반으로 접근을 제어하기 때문에 보안상 더 낫다고 판단했다.
• bastion 서버 자체의 유지비용과 관리 포인트가 줄어든다. bastion도 결국 EC2 인스턴스라 비용이 나가고, 패치나 키 관리 같은 운영 부담도 생긴다. SSM으로 전환하면 그 오버헤드를 없앨 수 있다.
• 접근 이력 추적이 편하다. SSM Session Manager는 세션 로그를 CloudWatch나 S3에 자동으로 남길 수 있어서, 누가 언제 어떤 인스턴스에 접근했는지 감사(audit) 추적이 훨씬 수월하다. bastion 방식에서는 이걸 별도로 구성해야 한다.

다만 bastion을 완전히 버려야 하나에 대해선 아직도 고민 중이다. 지금은 서비스 규모가 작아서 SSM으로도 충분하지만, EC2 수가 늘어나거나 현업 환경처럼 여러 인스턴스를 빠르게 오가며 관리해야 하는 상황이라면 SSH로 직접 붙는 게 더 편할 수 있기 때문이다.

Kafka가 그래서 뭔데?

kafka에대한 글을 읽는데 메세징 큐 서비스, 비동기 서비스 등 대부분의 글들이 잘 와닿지 않게 적혀있었다.

그래서 아주 기초적인 개념부터 파고자 했다.

Google cloud : Apache Kafka란 무엇인가요? 에서는 카프카에 대해 다음과 같이 정의한다:

"Apache Kafka는 별도의 시작이나 끝이 없는 스트리밍 이벤트 데이터 또는 일반 데이터를 수집, 처리, 저장하는 데 널리 사용되는 이벤트 스트리밍 플랫폼입니다. Kafka는 차세대 분산 애플리케이션이 확장을 통해 스트리밍 이벤트를 분당 수십억 개까지 처리할 수 있도록 합니다."

라고.

이 말은 너무 어렵게 적혀있는 것 같아 챗지피티의 도움을 받기로 했다.

하지만 이 설명은 조금 어렵게 느껴졌다.

그래서 ChatGPT의 도움을 받아 정리해 보았다.

여기서 한 가지 감이 잡히기 시작했다.

Kafka는 이벤트가 발생하면 그 기록을 저장하고, 필요한 서비스에게 전달해주는 시스템이라는 것이다.

즉,

• 어떤 일이 발생한다.
• 그 기록을 Kafka가 보관한다.
• 필요한 서비스들이 그 데이터를 가져가서 사용한다.

이렇게 이해할 수 있었다.

또한 여러 글을 읽어보니 내가 이해한 방향이 크게 틀리지 않았다는 것도 확인할 수 있었다.

Kafka는 데이터(이벤트 데이터, 일반 데이터, 사용자 행동 기록 등)를 저장하고 전달하는 역할을 한다.

그런 다음, Amazon에서 적은 kafka에 대한 글을 읽어보았다.

AWS - Kafka란 무엇입니까?

기초적인 개념을 이해하고 나니 Kafka에 대한 설명이 훨씬 읽히기 시작했다.

kafka가 어디에 사용되는가

aws에서 써있는 말이 조금 어려운 말이 있어서 쉽게 풀어 써보았다.

• "Kafka는 실시간 스트리밍 데이터 파이프라인을 구축하는 데 사용된다"

• 계속 발생하는 데이터를 여러 시스템으로 보내기 위해 Kafka를 사용한다.

• " 스트리밍 애플리케이션은 데이터 스트림을 소비한다"

• 다른 서비스들이 Kafka에서 데이터를 가져가서 처리한다.

• "Kafka는 메시지 브로커 역할을 한다"

• 서비스 사이에서 데이터를 대신 전달해주는 중간 서버이다.

따라서 이 글들을 보아 kafka는 계속 발생하는 데이터를 여러 시스템으로 보내기 위해, 중간 서버역할을 한다고 읽힐 수 있었다.

kafka와 비동기

Redhat - Apache Kafka란 무엇일까요?

다음으로 RedHat에서 작성한 Kafka 설명을 읽어보았다.

처음에는 긴 설명 때문에 조금 복잡하게 느껴졌다. 하지만 Kafka와 비동기의 관계를 이해하기 위해 하나씩 읽어보기로 했다.

먼저 동기 방식과 비동기 방식을 나눠서 생각해보았다.

일단 동기식 통신의 경우와 비동기 통신의 경우를 나눠 생각해보기로 한다.

동기식 통신 (API 호출)

이 방식은 우리가 평소에 알고 있는 방식이다.

• 주문서비스

• 결제 서비스 API 호출

• 주문 서비스

• 알림 서비스 API 호출

이런식으로 API를 호출하는 것을 동기식이라 한다.

특징

동기식 방식의 특징은 바로 응답을 기다리고, 상대 서비스가 죽으면 같이 문제가 발생한다는 것이다.

예를 들어,

• 주문 -> 결제 서버 다운 -> 주문도 실패

이런 형식으로 진행된다. 따라서 대규모 서비스에서 문제가 될 수 있다.

비동기식 통신 (kafka 사용)

비동기식 통신에 나온 것이 kafka이다. 이때에는 직접 호출하지 않고, 중간에 kafka에 이벤트를 남기는 것이다.

• 주문 서비스 -> kafka

이러면, 다른 서비스들이 알아서 kafka의 메세지를 가져가는 형식이다.

• 결제 서비스 -> kafka 읽음
• 알림 서비스 -> kafka 읽음
• 통계 서비스 -> kafka 읽음

특징

비동기 방식의 특징은 다음과 같다.

• 응답을 기다릴 필요가 없다.
• 서비스가 서로 독립적으로 동작한다.
• 확장이 쉽다.

Redhad 문장 다시 해석

그래서 다시 RedHat 문장을 해석해보면 다음과 같이 이해할 수 있다.

• "분산형 애플리케이션이 데이터를 공유하려면 통합이 필요하다."

• 여러 서비스가 데이터를 주고 받을 방법이 필요하다.

• "동기식 방법은 API를 활용한다."

• 서버가 다른 서버를 직접 호출하는 방식(동기식)

• "비동기식 방법은 중간 저장소를 사용한다."

• Kafka 같은 시스템에 데이터를 먼저 남긴다.

따라서 동기/비동기 형식의 글을 읽고 문장을 쉽게 해석하니 kafka가 어느 상황에 쓰이는 것인지, 비동기라는 것이 어떤 의미인지 이해할 수 있게 되었다.

kafka 한 문장 정리

Kafka는 서비스에서 발생하는 이벤트 데이터를 모아 저장하고, 필요한 다른 서비스들에게 비동기적으로 전달해주는 분산 스트리밍 플랫폼이다.

본 콘텐츠는 구름 서포터즈 활동으로 지원을 받아 작성된 교육생의 실제 경험 후기입니다.

3개월의 이론 기간이 끝나고 드디어 프로젝트를 시작하게 되었다. 그런데 중간에 설 연휴도 끼어 있어서 실질적으로는 약 1주일 정도 진행을 하지 못했다.

설 연휴 전에 프로젝트명과 도메인을 무엇으로 할지, 그리고 각자 어떤 역할을 맡을지 정도만 정해 놓은 상태였다.

이렇게 기본적인 틀을 정한 뒤, 전체적인 기술 스택은 초기에 EKS와 쿠버네티스를 활용한 MSA 구조로 시작하기로 수많은 토론 끝에 결정하였다.

위 사진은 그 열띤 토론의 한 장면이다.

첫 번째 기획안 발표

발표는 팀장인 내가 맡아 진행을 하게 되었다.

이렇게 PPT를 제작하여 발표를 진행하였다. 여기까지는 비교적 수월하게 진행되는 것처럼 보였다.

첫 멘토링, 그리고 와장창 깨진 우리의 기획안

우리는 PPT도 만들었고 발표도 무난하게 마쳤기 때문에 기술 선택에 대해 어느 정도 자신감이 있었다. 하지만 실제 여러 회사를 다니며 우리와 같은 과정을 겪어오신 멘토님께서는 꽤 날카로운 질문을 던지셨다.

처음부터 MSA로 시작하는 것이 맞는지, EC2만으로도 충분히 가능한데 왜 EKS를 사용하려 하는지, EKS 안에는 어떤 구성요소들이 있고 그래서 왜 비용이 많이 나오는지 알고 있는지 등 생각보다 기본적인 질문들이 이어졌다.

하지만 우리는 그 질문들에 대해 명확하게 답변하지 못했다.

결국 멘토링 이후 프로젝트 방향을 다시 잡게 되었다. 처음부터 거대한 구조를 만드는 것이 아니라, 먼저 모놀리식 구조로 서비스를 구성하고 그 안에서 문제점을 발견한 뒤 점진적으로 확장해 나가는 방식으로 기획을 전면 수정하기로 했다.

-> 이는 멘토님께서 지적한 부분을 정리한 것이다.

멘토링을 하면서 가장 크게 느낀 점이 있다. 우리는 최신 기술을 적용하는 것 자체에 너무 집중하고 있었고, 기술을 위한 프로젝트를 하려고 했던 것 같다.

하지만 결국 중요한 것은 기술의 화려함이 아니라 왜 이 기술을 사용하는지 이해하고 선택하는 과정이라는 것을 깨달았다.

시간이 조금 부족하더라도 기초부터 차근차근 쌓아 가는 방식이 결국 우리에게 더 많이 남는 프로젝트가 될 것이라는 확신이 들었다.

멘토링을 한 것은 프로젝트 중 가장 잘한 일이라고 생각한다. 우리가 잘못가고 있는 길을, 애써 무시한 것들을 잘 짚어주셔서 감사하다고 생각이 든다.

본 콘텐츠는 구름 서포터즈 활동으로 지원을 받아 작성된 교육생의 실제 경험 후기입니다.

오늘은 구름의 딥다이브 과정을 반 정도 지나온 시점에서, 약 3개월 동안 느낀 점을 정리해보려고 한다. 또한 과정이 어떻게 진행되는지 간략하게 소개하고, 그중에서도 가장 마음에 들었던 스터디에 관해 이야기하려고 한다.

딥다이브 홈페이지 및 EXP 미션

우선 딥다이브 홈페이지는 위와 같이 구성되어 있으며, EXP로 이동할 수 있다.

EXP로 이동하면 이러한 화면이 나온다.

그 다음에는 미션 탭으로 이동하게 된다.

미션 탭에서는 다양한 미션을 도전하고 완료할 수 있다. 미션을 수행하는 것은 자유이지만, 커리큘럼에 맞춰 난이도가 점점 올라가는 구조로 되어있다.

수업을 듣고 난 뒤 미션을 하나씩 클리어하는 과정에서, 강의에서 배웠던 내용을 자연스럽게 실습하고 복습할 수 있어 도움이 많이 되는 것 같다.

미션을 완료한 뒤에는 강사님께 결과 제출과 피드백을 받게 된다. 이 과정에서 강사님이 남겨주시는 짧은 응원 한마디가 오래 기억에 남았고, 더 열심히 하게 되는 원동력이 되었다.

그 다음으로는 칭찬하기 탭도 확인할 수 있다.

공개적으로 타인을 칭찬하는 것이 처음에는 조금 부끄러웠지만, 용기를 내어 강사님 칭찬하기 미션을 수행하며 평소 전하고 싶었던 말을 전달해보았다.

강사님께서는 이렇게 진심을 담아 답글을 남겨주셨고, 딥다이브 과정을 시작하는 데 큰 힘이 되었던 것 같다.

스터디

딥다이브 과정 중에는 스터디가 필수로 진행되었다.

딥다이브 과정중에는 스터디가 필수로 되어있었다.

나는 팀빌딩 게시판에 글을 올려 도커와 쿠버네티스를 함께 공부할 팀원들을 모았다.

또한 12월 31일까지 인프런 제공 기간에 맞춰, 팀원들과 쿠버네티스, 프로메테우스, 그라파나 강의를 완강하는 것을 목표로 계획을 세웠다. 강의를 함께 들으며 내용을 공유하고 정리하는 방식으로 스터디를 진행하였다.

https://www.notion.so/goormkdx/1-296c0ff4ce3181068983cc8b23e5b945

위 링크는 우리 스터디 팀원들이 함께 사용하는 노션 페이지이다.

이렇게 진행 방식과 공통 목표를 설정하고, 구체적인 계획을 세운 뒤 스터디를 이어갔다.

그날그날 각자가 공부한 내용과 포스팅한 글을 공유하면서 서로의 학습에 큰 도움을 주고 있다.

이론 기간이 짧게 느껴지기도 했지만, 그 시간 동안 서로 동기부여를 주고받으며 아무것도 몰랐던 쿠버네티스와 프로메테우스, 그라파나를 공부하면서 많은 성장을 이룰 수 있었던 것 같다.

또한 이 스터디는 하루 한 시간 정도만 진행되었지만, 남는 자습 시간에도 서로 공부하고 의견을 나누며 딥다이브 과정 중 개인적으로 가장 만족하고 있는 시간으로 남아 있다.

쿠키 동작 과정 (기본 흐름)

• 1. 클라이언트(브라우저)가 페이지를 요청한다. ex)사용자가 사이트에 접속

     GET /login

• 2. 웹서버는 쿠키를 생성한다. ex) 로그인 세션 ID 만들기

• 3. 서버는 응답(Response) 헤더에 쿠키를 담아서 보낸다.

     • 즉, 서버가 브라우저에게 해당 내용을 쿠키로 저장하라고 하는 것이다.

       Set-Cookie: sessionId=abc123; Path=/; HttpOnly

• 4. 브라우저는 쿠키를 저장한다.

• 5. 이후 같은 사이트 요청 시 브라우저가 쿠키를 자동으로 첨부한다. ex) 사용자가 다시 요청한다.

• 브라우저는 자동으로 붙인다.

     Cookie: sessionId=abc123

• 6. 서버는 쿠키 값을 읽고 사용자를 식별한다. (서버는 sessionID를 보고 로그인 한 사용자라고 판단한다.)

• 7. 서버는 쿠키를 갱신하거나 삭제할 수도 있다
  • 만료 연장

    Set-Cookie: sessionId=abc123; Max-Age=3600

  • 삭제

    Set-Cookie: sessionId=; Max-Age=0

• 8. 브라우저는 만료되면 쿠키를 자동 삭제한다.
  • Max-Age, Expires 지나면 제거된다.

실습으로 쿠키 생성과정 확인하기

실습 순서는 다음과 같다.

1. 개발자 도구를 연다.

f12를 누르면 개발자 도구를 열 수 있다.

2. 개발자 도구에서 Network탭을 누른다.

3. 새로고침을 한 후, 요청들에서 type이 document인 줄 하나를 클릭한다.

4. 상세 Header 패널을 연다

5. Response Headers에서 Set-Cookie 항목을 확인한다

그럼 다음과 같이 set-cookies정보들을 볼 수 있다. 이것에 의미는 서버에서 쿠키를 내려줬다는 것이다.

6. Cookies 탭을 본다.

아까 Header에 들어가서 response Header에 있는 set-cookie에 있는 내용이 Response Cookies에 표 형태로 잘 들어가있는 것을 확인할 수 있다.

• Response Cookies: 서버가 내려준 쿠키

• Request Cookies: 브라우저가 다음 요청에 자동으로 첨부한 쿠키

즉, 쿠키는 서버에서 내려온 뒤 브라우저에 저장되고 이후 요청마다 자동으로 포함되어 서버로 전달되는 구조이다

정리

• Set-Cookie는 서버가 쿠키를 생성해서 내려주는 순간이다.
• Cookie는 브라우저가 저장된 쿠키를 자동으로 요청에 포함시키는 것이다.
• 개발자 도구 Network 탭을 통해 쿠키의 생성과 전달 흐름을 직접 확인할 수 있다.

이 포스팅은 쿠버네티스 공식 문서를 따라가며 설치 전 사전 조건부터 컨테이너 런타임, 네트워크 플러그인까지 “왜 이 설정이 필요한지”를 중심으로 정리한 기록이다.

쿠버네티스 공식 홈페이지 - kubeadm

이렇게 쿠버네티스 공식 홈페이지에 들어가게되면 기초적으로 확인할 , 필수포트와 스왑 구성을 해야한다고 나와있다.

1. 필수 포트 확인

필수 포트 확인에 대한 내용은 아래 공식 문서를 참고하였다. 쿠버네티스 공식 홈페이지 - 포트와 프로토콜

쿠버네티스 설치 전에는 필수 포트가 네트워크 상에서 차단되어 있지 않은지를 확인해야 한다. 이는 해당 포트에 서비스가 이미 실행 중이어야 한다는 의미가 아니라, 설치 이후 쿠버네티스 컴포넌트들이 사용할 수 있도록 포트가 열려 있어야 한다는 의미이다.

대표적으로 쿠버네티스 API 서버는 기본적으로 6443/TCP 포트를 사용한다.

다음은 API 서버 포트를 확인할 때 사용할 수 있는 명령어 예시이다.

nc 127.0.0.1 6443 -zv -w 2

이 명령은 다음을 의미한다.

• 127.0.0.1 : 로컬 노드
• 6443 : 쿠버네티스 API 서버 포트
• -z : 실제 데이터 전송 없이 포트 상태만 확인
• -v : 상세 출력
• -w 2 : 타임아웃 2초

실제 실행 결과와 그 의미

로컬 환경에서 위 명령을 실행했을 때 다음과 같은 출력이 나타났다.

이 결과는 포트가 차단되어 있다는 의미가 아니다.

Connection refused 는 해당 IP와 포트에 현재 리스닝 중인 프로세스가 존재하지 않는다는 의미이다.

즉, 다음과 같은 상황을 의미한다.

• 방화벽에 의해 포트가 막힌 상태 → 아님
• 해당 노드에 API 서버 프로세스가 실행 중 → 아님

본 실습 환경에서는 이 명령을 쿠버네티스 컨트롤 플레인 노드가 아닌 로컬 PC에서 실행했기 때문에, 127.0.0.1:6443 에 kube-apiserver 프로세스가 존재하지 않아 위와 같은 결과가 출력되었다.

공식 문서의 예제를 어떻게 이해해야 하는가

중요한 점은, 공식 문서에 제시된 nc 명령이 쿠버네티스 설치 전에 반드시 실행해야 하는 절차는 아니라는 점이다. (그래서 현재 시점에서는 중요한게 아니다.)

해당 예제는 다음을 설명하기 위한 것이다.

쿠버네티스 API 서버는 기본적으로 6443 포트를 사용한다

설치 이후, 또는 운영 중 장애 상황에서

API 서버 포트가 정상적으로 열려 있는지 이런 방식으로 확인할 수 있다

즉, 설치 전 단계에서는 이 명령의 성공 여부를 확인하는 것이 목적이 아니라, 해당 포트가 방화벽·네트워크 정책 상 차단되지 않도록 사전에 설계되어 있어야 한다는 점을 인지하는 것이 목적이다.

2. 스왑 구성

스왑(Swap) 구성에 대해서는 쿠버네티스 공식 문서에서 다음과 같이 명시하고 있다.

쿠버네티스에서 kubelet은 기본적으로 스왑 메모리가 활성화되어 있으면 실행에 실패하도록 설계되어 있다. 이는 쿠버네티스가 노드의 메모리 상태를 정확하게 인지하고, 파드의 리소스 사용량을 안정적으로 제어하기 위함이다.

왜 쿠버네티스는 스왑을 허용하지 않을까

리눅스에서 스왑은 물리 메모리가 부족할 때 디스크 공간을 메모리처럼 사용하는 기능이다.

하지만 쿠버네티스 환경에서는 이 방식이 문제가 된다.

• 스왑은 디스크 I/O를 사용하기 때문에 성능 예측이 어렵다
• kubelet은 파드의 메모리 사용량을 기준으로 스케줄링과 eviction을 수행한다
• 스왑이 활성화되어 있으면 실제 메모리 사용량을 정확히 판단하기 어렵다

이로 인해 쿠버네티스는 “메모리가 부족하면 느리게 버티는 것”보다 “명확하게 OOM을 발생시키는 것”을 더 안전한 동작으로 판단한다.

그래서 기본 정책은 다음과 같다.

스왑이 켜져 있으면 kubelet은 실행되지 않는다.

스왑 비활성화 방법

쿠버네티스를 설치하기 위해서는 노드에서 스왑을 비활성화해야 한다.

우선 현재 활성화된 스왑을 즉시 비활성화한다.

swapoff -a

이 명령은 현재 실행 중인 시스템에서만 스왑을 끄는 임시 설정이다.

재부팅 후에도 스왑이 다시 활성화되지 않도록 하기 위해 /etc/fstab 파일에서 스왑 설정을 주석 처리한다.

sed -i '/ swap / s/^/#/' /etc/fstab

이렇게 설정하면 시스템 재부팅 이후에도 스왑이 비활성화된 상태를 유지한다.

현재 스왑 활성화 여부 확인

swapon --show

아무 출력도 없으면 → 스왑 비활성화 상태이다

출력이 있으면 → 스왑 활성화 상태이다

나는 현재 이렇게 스왑이 비활성화된 상태라고 출력이 된다.

여기서 더 자세하기 보기 위해서 다음 명령어를 쳐봤다.

free -h

여기서 Swap: 0B 0B 0B 로 나오면 완전히 비활성화 상태이다.

3. 컨테이너 런타임 설치

마지막으로 쿠버네티스를 설치하기 위해서는 컨테이너 런타임을 설치해야 한다. 쿠버네티스는 자체적으로 컨테이너를 실행하지 않기 때문에, 외부 컨테이너 런타임이 반드시 필요하다. 본 실습에서는 쿠버네티스 공식 문서에서 권장하는 containerd를 컨테이너 런타임으로 사용한다.

일단 위 글에서 살펴보라고 나온 컨테이너 런타임에 들어가서 보면 다음과 같이 나온다.

컨테이너 런타임을 설치하기 전에 리눅스 커널 파라미터를 사전에 설정해야 한다는 내용이 나온다.

위 문서에서는 다음과 같은 sysctl 설정을 적용하도록 안내하고 있다.

이 설정들은 단순히 containerd만을 위한 설정이 아니라, 쿠버네티스 파드 네트워크가 정상적으로 동작하기 위해 필수적인 커널 설정이다.

3-1. sysctl 설정

sysctl 설정이 필요한 이유.

쿠버네티스에서 파드는 가상 네트워크를 통해 서로 통신한다. 이 과정에서 리눅스 커널은 다음과 같은 역할을 수행해야 한다.

• 브리지 네트워크를 통해 들어오는 패킷을 iptables에서 처리할 수 있어야 한다
• 파드 간 트래픽이 노드를 거쳐 포워딩될 수 있어야 한다
• 컨테이너 네트워크 인터페이스(CNI)가 커널 네트워크 스택과 정상적으로 연동되어야 한다

하지만 리눅스 기본 설정에서는 브리지 네트워크를 통과하는 패킷이 iptables 규칙을 거치지 않거나, IP 포워딩이 비활성화되어 있는 경우가 많다.

이 상태로 쿠버네티스를 설치하면 다음과 같은 문제가 발생할 수 있다.

• 파드 간 통신 실패
• 서비스(Service) 트래픽이 정상적으로 전달되지 않음
• CNI 플러그인 초기화 실패

이를 방지하기 위해, 공식 문서에서는 아래와 같은 커널 파라미터 설정을 사전 조건으로 요구한다.

적용하는 sysctl 파라미터의 의미

net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1

위 설정은 브리지 네트워크를 통해 전달되는 패킷이 iptables 및 ip6tables 규칙을 거치도록 설정하는 옵션이다.

즉, 쿠버네티스 네트워크 정책과 서비스 규칙이 브리지 인터페이스에서도 정상적으로 적용되도록 하기 위한 설정이다.

net.ipv4.ip_forward = 1

이 설정은 IP 포워딩을 활성화하는 옵션이다. 노드가 파드 트래픽을 다른 파드나 노드로 전달하기 위해 반드시 필요하다.

sysctl 파라미터 적용

공식 문서에서 제시한 명령어를 그대로 사용하여 해당 커널 파라미터를 적용한다.

이 설정은 컨테이너 런타임(containerd) 설치 이전에 적용되어야 하며, 이후 CNI 플러그인과 쿠버네티스 네트워크가 정상적으로 동작하기 위한 기반이 된다.

3-2. cgroup 드라이버

컨테이너 런타임을 설치할 때 반드시 함께 고려해야 하는 요소가 cgroup(control group) 드라이버이다.

리눅스에서 cgroup은 프로세스에 할당된 CPU, 메모리, I/O와 같은 자원을 제한하고 관리하기 위한 기능이다. 쿠버네티스에서는 이 cgroup을 기반으로 파드와 컨테이너의 리소스를 제어한다.

kubelet과 컨테이너 런타임에서 cgroup이 중요한 이유

쿠버네티스에서 실제 컨테이너를 관리하는 주체는 다음 두 컴포넌트이다.

• kubelet
• 컨테이너 런타임(containerd)

이 두 컴포넌트는 모두 cgroup을 통해 다음과 같은 작업을 수행한다.

• 파드의 CPU / 메모리 요청(request)과 제한(limit) 적용
• 노드의 리소스 사용량 추적
• 메모리 부족 상황에서 파드 eviction 판단

이 때문에 kubelet과 컨테이너 런타임은 반드시 동일한 cgroup 드라이버를 사용해야 한다. 두 컴포넌트가 서로 다른 방식으로 cgroup을 관리할 경우, 노드의 리소스 상태를 서로 다르게 인식하게 되어 시스템이 불안정해질 수 있다.

사용 가능한 cgroup 드라이버 종류

쿠버네티스에서 사용할 수 있는 cgroup 드라이버는 크게 두 가지이다.

• cgroupfs
• systemd

cgrupfs 드라이버

cgroupfs 드라이버는 kubelet이 직접 cgroup 파일 시스템을 제어하는 방식이다.

과거에는 기본값으로 많이 사용되었지만, init 시스템이 systemd인 환경에서는 권장되지 않는다.

그 이유는 systemd 자체가 이미 cgroup 관리자 역할을 수행하고 있기 때문이다. 이 상태에서 cgroupfs를 사용하면, 하나의 시스템에 두 개의 cgroup 관리자(systemd + cgroupfs) 가 공존하게 되어 리소스 관리 충돌이 발생할 수 있다.

systemd cgroup 드라이버

systemd cgroup 드라이버는 systemd를 통해 cgroup을 관리하는 방식이다.

systemd 기반 리눅스 배포판에서는 모든 서비스와 프로세스가 systemd 단위(unit)로 관리되며, 각 단위마다 cgroup이 자동으로 할당된다.

따라서 systemd를 init 시스템으로 사용하는 환경에서는 kubelet과 컨테이너 런타임 모두 systemd cgroup 드라이버를 사용하는 것이 권장된다.

공식 문서에서도 systemd 환경에서는 systemd cgroup 드라이버 사용을 권장하고 있으며, 특히 cgroup v2 환경에서는 systemd 사용이 사실상 표준에 가깝다.

본 실습 환경에서의 선택

앞서 살펴본 cgroup 드라이버 개념을 바탕으로, 본 실습 환경에서는 다음과 같은 구성을 선택하였다.

본 실습은 systemd 기반의 Rocky Linux 환경에서 진행되었으며, 컨테이너 런타임으로는 containerd를 사용하였다.

이에 따라 kubelet과 컨테이너 런타임 간의 cgroup 관리 방식을 일치시키기 위해 systemd cgroup 드라이버를 사용하도록 설정하였다.

실제로 containerd 설정 파일을 생성한 뒤, 기본값으로 설정되어 있는 cgroupfs 방식이 아닌 systemd 방식으로 cgroup 드라이버를 변경하였다.

3-3 컨테이너 런타임 설치

공식 문서에는 다음과 같은 컨테이너 런타임들이 소개되어 있다.

• containerd
• CRI-O
• Docker 엔진 (cri-dockerd 사용)
• 미란티스 컨테이너 런타임(MCR)

이 중에서 본 실습에서는 containerd를 컨테이너 런타임으로 선택하였다.

containerd를 선택한 이유

containerd는 CNCF에서 관리되는 오픈소스 컨테이너 런타임으로, 쿠버네티스가 공식적으로 지원하는 CRI 호환 런타임이다.

containerd를 사용할 경우 다음과 같은 특징이 있다.

• 별도의 어댑터 없이 kubelet과 직접 CRI 연동 가능
• Docker 엔진에 비해 구조가 단순함
• 쿠버네티스 공식 문서에서 권장하는 기본 런타임
• 현재 운영 환경에서 가장 널리 사용되는 런타임 중 하나

반면, Docker 엔진은 쿠버네티스 1.24 버전부터 kubelet 내장 지원이 제거되었기 때문에 추가 어댑터인 cri-dockerd를 설치해야만 사용이 가능하다.

본 실습에서는 불필요한 중간 계층을 줄이고, 공식 권장 구조에 맞추기 위해 Docker 엔진 및 cri-dockerd는 사용하지 않았다.

containerd 설치 및 CRI 엔드포인트

containerd를 설치하면, 다음 경로에 CRI 소켓이 생성된다.

/var/run/containerd/containerd.sock

kubeadm은 이 소켓을 통해 containerd가 CRI 런타임으로 동작하고 있음을 자동으로 인식한다.

따라서 본 실습에서는 kubeadm 실행 시 별도로 컨테이너 런타임 엔드포인트를 지정하지 않아도 containerd를 정상적으로 감지하여 클러스터 초기화를 진행할 수 있다.

containerd 설정 파일과 cgroup 드라이버

공식 문서에서는 containerd 설치 이후 유효한 설정 파일(config.toml)을 생성하고, systemd cgroup 드라이버를 사용하도록 설정할 것을 권장한다.

이에 따라 본 실습에서는 기본 설정 파일을 생성한 뒤 cgroup 드라이버를 systemd 방식으로 변경하였다.

이 설정을 통해

• kubelet
• containerd

두 컴포넌트가 동일한 cgroup 관리 방식을 사용하도록 구성하였다.

설정 변경 이후에는 containerd 서비스를 재시작하여 변경 사항을 적용하였다.

3-4 네트워크 플러그인

공식 홈페이지에서는 이렇게, 컨테이너 런타임 뿐만 아니라 클러스터에 동작하는 네트워크 플러그인도 필요하다고 나와있어 네트워크 플러그인도 설치해준다.

쿠버네티스 공식 홈페이지 - 네트워크 플러그인

위 링크를 들어가면 다음과 같이 나온다.

네트워크 플러그인이 필요한 이유

쿠버네티스에서 파드는 노드 안에서 생성되고 삭제되며, 클러스터 상태에 따라 언제든지 다른 노드로 이동할 수 있다.

이때 다음과 같은 작업이 필요하다.

• 파드 생성 시 IP 할당
• 파드 삭제 시 IP 회수
• 파드 간 통신 경로 구성
• 노드 간 파드 트래픽 라우팅
• 서비스(Service) 트래픽 처리

이 모든 네트워크 관련 작업을 담당하는 것이 네트워크 플러그인이다.

따라서 네트워크 플러그인이 설치되지 않은 상태에서는 다음과 같은 현상이 발생한다.

• 파드는 생성되지만 NotReady 상태에 머무른다
• 파드 간 통신이 불가능하다
• CoreDNS가 정상적으로 동작하지 않는다
• 서비스(Service)를 통한 접근이 불가능하다

즉, 네트워크 플러그인이 없으면 쿠버네티스 클러스터는 사실상 정상 동작할 수 없다.

CNI(Container Network Interface)

쿠버네티스는 네트워크 플러그인과 연동하기 위해 CNI(Container Network Interface) 라는 표준 인터페이스를 사용한다.

CNI는 다음을 정의한다.

• 컨테이너 네트워크를 설정하는 방식
• 네트워크 플러그인이 kubelet과 통신하는 방법
• 파드 생성/삭제 시 네트워크를 설정·정리하는 규칙

쿠버네티스는 CNI 규격을 만족하는 플러그인이라면 어떤 구현체라도 사용할 수 있도록 설계되어 있다.

네트워크 플러그인의 종류

공식 문서에는 다양한 네트워크 플러그인이 소개되어 있다.

예를 들면 다음과 같다.

• Calico
• Flannel
• Weave Net
• Cilium

각 플러그인은 네트워크 구현 방식, 성능 특성, 보안 기능(NetworkPolicy 지원 여부) 등이 서로 다르다.

따라서 실제 운영 환경에서는 클러스터 규모, 보안 요구사항, 네트워크 정책 적용 여부 등을 고려하여 적절한 네트워크 플러그인을 선택해야 한다.

본 실습에서의 네트워크 플러그인 선택

본 실습 환경에서는 네트워크 플러그인으로 Calico를 사용한다.

Calico는

• 쿠버네티스 NetworkPolicy를 기본적으로 지원하며
• 노드 간 파드 통신을 안정적으로 처리하고
• 공식 문서와 실습 자료에서 널리 사용되는 플러그인이다

다음 단계에서는 kubeadm을 통해 클러스터를 초기화한 이후, Calico 네트워크 플러그인을 설치하여 파드 네트워크를 실제로 구성한다.

이제는 이해할 수 있는 쿠버네티스 설치 명령어(Full)

echo '======== [4] Rocky Linux 기본 설정 ========'
echo '======== [4-1] 패키지 업데이트 ========'
# 강의와 동일한 실습 환경을 유지하기 위해 Linux Update는 하지 마세요!
# yum -y update # (x)

echo '======== [4-2] 타임존 설정 ========'
timedatectl set-timezone Asia/Seoul
timedatectl set-ntp true
chronyc makestep

echo '======== [4-3] [WARNING FileExisting-tc]: tc not found in system path 로그 관련 업데이트 ========'
yum install -y yum-utils iproute-tc
echo '======== [4-3] [WARNING OpenSSL version mismatch 로그 관련 업데이트 ========'
yum update openssl openssh-server -y

echo '======= [4-4] hosts 설정 =========='
cat << EOF >> /etc/hosts
192.168.56.30 k8s-master
EOF

echo '======== [5] kubeadm 설치 전 사전작업 ========'
echo '======== [5] 방화벽 해제 ========'
systemctl stop firewalld && systemctl disable firewalld

echo '======== [5] Swap 비활성화 ========'
swapoff -a && sed -i '/ swap / s/^/#/' /etc/fstab

echo '======== [6] 컨테이너 런타임 설치 ========'
echo '======== [6-1] 컨테이너 런타임 설치 전 사전작업 ========'
echo '======== [6-1] iptable 세팅 ========'
cat <<EOF |tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

modprobe overlay
modprobe br_netfilter

cat <<EOF |tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sysctl --system

echo '======== [6-2] 컨테이너 런타임 (containerd 설치) ========'
echo '======== [6-2-1] containerd 패키지 설치 (option2) ========'
echo '======== [6-2-1-1] docker engine 설치 ========'
echo '======== [6-2-1-1] repo 설정 ========'
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

echo '======== [6-2-1-1] containerd 설치 ========'
yum install -y containerd.io-1.6.21-3.1.el9.aarch64
systemctl daemon-reload
systemctl enable --now containerd

echo '======== [6-3] 컨테이너 런타임 : cri 활성화 ========'
containerd config default > /etc/containerd/config.toml
sed -i 's/ SystemdCgroup = false/ SystemdCgroup = true/' /etc/containerd/config.toml
systemctl restart containerd

echo '======== [7] kubeadm 설치 ========'
echo '======== [7] repo 설정 ========'
cat <<EOF | sudo tee /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://pkgs.k8s.io/core:/stable:/v1.27/rpm/
enabled=1
gpgcheck=1
gpgkey=https://pkgs.k8s.io/core:/stable:/v1.27/rpm/repodata/repomd.xml.key
exclude=kubelet kubeadm kubectl cri-tools kubernetes-cni
EOF

echo '======== [7] SELinux 설정 ========'
setenforce 0
sed -i 's/^SELINUX=enforcing$/SELINUX=permissive/' /etc/selinux/config

echo '======== [7] kubelet, kubeadm, kubectl 패키지 설치 ========'
yum install -y kubelet-1.27.2-150500.1.1.aarch64 kubeadm-1.27.2-150500.1.1.aarch64 kubectl-1.27.2-150500.1.1.aarch64 --disableexcludes=kubernetes
systemctl enable --now kubelet

echo '======== [8] kubeadm으로 클러스터 생성  ========'
echo '======== [8-1] 클러스터 초기화 (Pod Network 세팅) ========'
kubeadm init --pod-network-cidr=20.96.0.0/12 --apiserver-advertise-address 192.168.56.30

echo '======== [8-2] kubectl 사용 설정 ========'
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

echo '======== [8-3] Pod Network 설치 (calico) ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/calico-3.26.4/calico.yaml
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/calico-3.26.4/calico-custom.yaml

echo '======== [8-4] Master에 Pod를 생성 할수 있도록 설정 ========'
kubectl taint nodes k8s-master node-role.kubernetes.io/control-plane-

echo '======== [9] 쿠버네티스 편의기능 설치 ========'
echo '======== [9-1] kubectl 자동완성 기능 ========'
yum -y install bash-completion
echo "source <(kubectl completion bash)" >> ~/.bashrc
echo 'alias k=kubectl' >>~/.bashrc
echo 'complete -o default -F __start_kubectl k' >>~/.bashrc
source ~/.bashrc

echo '======== [9-2] Dashboard 설치 ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/dashboard-2.7.0/dashboard.yaml

echo '======== [9-3] Metrics Server 설치 ========'
kubectl create -f https://raw.githubusercontent.com/k8s-1pro/install/main/ground/k8s-1.27/metrics-server-0.6.3/metrics-server.yaml

위 포스팅은 인프런 강의 : 쿠버네티스 어나더 클래스-Sprint 1, 2 및 쿠버네티스 무게감 있게 설치하기를 참고하여 작성한 포스팅입니다.

컨테이너 이전 배포방식

컨테이너가 등장하기 전의 배포 방식은 비교적 단순한 구조였다. 애플리케이션을 빌드해서 나온 실행 파일을 서버에 복사하고 실행하는 방식이다.

개발 환경

• 개발자는 IntelliJ 같은 IDE를 사용해 코드를 작성한다.
• 개발이 완료되면 Gradle 같은 빌드 도구를 통해 빌드를 수행한다. 빌드는 컴파일 후, 실행 가능한 형태로 패키징하는 과정이다.
• ex) Java로 개발한 경우, 빌드를 하면 .jar 파일이 생성된다.
• 이 .jar 파일은 사전에 설치된 JVM(Java Virtual Machine) 위에서 실행된다

많은 개발자들은 이러한 환경을 자신의 컴퓨터에 설치하고, 코딩하고 테스트하면서 개발을 진행한다.

• 각자 개발이 완료되면 소스를 GitHub에 커밋한다.
• GitHub에 코드가 통합된 이후, Jenkins 같은 CI 도구를 통해 빌드를 수행한다

CI/CD 환경

• Jenkins는 GitHub에서 소스를 내려받는다.
• Jenkins 서버에도 Gradle이 설치되어 있어 필요한 라이브러리를 내려받는다.
• 빌드를 통해 .jar 파일을 생성한다.
• 생성된 .jar 파일을 인프라 서버에 배포하면 배포가 완료된다.

(이 구조에서는 “서버에 JVM이 깔려 있고, 거기에 jar만 올리면 된다” 라는 전제가 항상 필요하다.)

컨테이너가 나온 후 배포방식

컨테이너 이전에는 .jar 파일을 서버에 복사하면 배포가 끝이었다.

하지만 컨테이너가 등장하면서 배포 방식에 중요한 변화가 생겼다.

가장 큰 변화는, 컨테이너 빌드 과정이 추가되었다는 점이다.

CI/CD 환경 (컨테이너 기반)

Jenkins에서 빌드 버튼을 눌렀을 때 다음과 같은 일이 순서대로 발생한다.

• 먼저 .jar 파일을 실행할 수 있는 OpenJDK 이미지를 DockerHub에서 가져온다.
• 이 OpenJDK 이미지는 애플리케이션을 실행하기 위한 베이스 이미지이다.
• 그 위에 빌드된 .jar 파일을 올린다.
• 이 과정을 통해 컨테이너 이미지가 생성된다. → MyApp 컨테이너 이미지
• 생성된 이미지를 다시 DockerHub 같은 이미지 레지스트리에 업로드한다.

즉, 이제 배포 대상은 jar 파일이 아니라 컨테이너 이미지가 된다.

배포 과정

컨테이너 이미지가 준비되면 배포가 진행된다. Jenkins에서 쿠버네티스에 Pod 생성 명령을 전달한다.

인프라 환경 (Kubernetes)

이 명령을 받은 쿠버네티스는 다음과 같이 동작한다.

• Pod 정의 안에는 컨테이너 이미지 주소가 들어 있다.
• 쿠버네티스는 해당 주소를 보고 DockerHub에서 이미지를 다운로드한다.
• 그 다음, containerd에게 해당 이미지로 컨테이너를 생성하라고 요청한다.
• containerd는 이미지를 기반으로 실제 컨테이너를 실행한다.

이렇게 해서 애플리케이션이 실행된다.

핵심 차이

컨테이너 이전 : -> jar 파일을 서버에 직접 배포 컨테이너 이후 : -> jar 파일을 포함한 컨테이너 이미지를 빌드하고 배포.

컨테이너가 나온 덕분에

• 실행 환경이 이미지로 고정되고
• 서버마다 환경 차이로 인한 문제가 줄어들며
• 배포와 롤백이 훨씬 쉬워졌다.

위 포스팅은 인프런 강의 중 쿠버네티스 어나더 클래스-Sprint 1, 2를 참고하여 작성하였습니다.

리눅스는 크게 Debian 계열과 Red Hat 계열로 나눌 수 있다. 이 구분은 무료/유료의 문제가 아니라, 패키지 관리 방식과 배포 정책의 계열 차이이다.

• Debian 계열은 apt, dpkg 기반의 패키지 관리 방식을 사용한다.
• Red Hat 계열은 rpm, dnf(yum) 기반의 패키지 관리 방식을 사용한다.

Debian 계열에서 가장 대중적으로 사용되는 배포판은 Ubuntu이다. Ubuntu는 Debian을 기반으로 하되, 설치 편의성, 드라이버 지원, 빠른 릴리스 주기 등을 강화한 배포판이다. 이 때문에 개인 개발 환경, 서버 테스트, 컨테이너 베이스 이미지 등에서 매우 많이 사용된다.

Red Hat 계열의 대표적인 배포판은 RHEL(Red Hat Enterprise Linux)이다. RHEL은 기업 환경을 대상으로 한 상용 리눅스로, 긴 지원 기간(LTS), 안정적인 업데이트, 공식 기술 지원을 제공한다. 다만 라이센스 비용이 많이 발생한다.

RHEL은 소스가 공개되기 때문에, 이를 기반으로 한 호환 배포판들이 존재한다. 대표적으로 Rocky Linux, AlmaLinux가 있다.

과거에는 CentOS가 이 역할을 했으나, 현재는 사용하지 않는다.

그 대안으로 Rocky Linux와 AlmaLinux가 등장했으며 현재 점유율은 Rocky Linux가 높다.

기업 환경에서는 RHEL과 바이너리 호환을 유지하면서 무료로 사용할 수 있는 Rocky Linux를 표준처럼 사용하는 경우가 많다.

나는 리눅스의 역사를 공부하면서 무료인 Ubuntu를 쓰면 되는 것 아닌가라는 생각이 들 수 있지만, 기업 환경에서는 단순한 무료 여부보다 운영 안정성, 업데이트 정책, 표준화된 관리 방식이 훨씬 중요하다는 것을 깨닫게 되었다.

Ubuntu는 릴리스 주기가 빠르고 변화가 잦지만, Red Hat 계열은 변경 폭이 작고 장기간 동일한 환경을 유지하기 때문에 Red Hat을 선호한다는 것을 알게 되었다.

따라서 OS를 직접 관리하는 비용과 리스크를 줄이기 위해 기업에서는 Rocky Linux와 같은 Red Hat 계열 배포판을 선호하는 경우가 많다는 것을 알게 되었다.

컨테이너와 컨테이너 런타임, 컨테이너 오케스트레이션

컨테이너, 컨테이너 런타임

컨테이너는 애플리케이션과 실행 환경을 함께 묶은 실행 단위이다. 이 컨테이너를 실제로 생성하고 실행하는 역할을 하는 것이 컨테이너 런타임이다.

우리가 잘 아는 Docker는 단순한 도구 하나가 아니라, 내부에 컨테이너 런타임 기능을 포함한 플랫폼이다.

• 이미지를 빌드하고
• 컨테이너를 생성하고
• 컨테이너를 실행하고 관리한다

즉, 컨테이너가 결과물이라면, 컨테이너 런타임은 컨테이너를 실행시키는 엔진이다.

컨테이너 런타임의 예시는 다음과 같다.

ex) Docker, containerd, CRI-O

이 중 containerd는 Docker에서 분리되어 나온 핵심 런타임으로, 현재 쿠버네티스 환경에서 가장 널리 사용되고 있다.

컨테이너 오케스트레이션

컨테이너 오케스트레이션이란 이러한 컨테이너 런타임 위에서 실행되는 수많은 컨테이너들을 자동으로 관리·조정하는 시스템이다.

• 컨테이너 배포
• 스케일 아웃/인
• 장애 발생 시 재시작
• 로드 밸런싱

이 역할을 수행하는 대표적인 도구가 쿠버네티스이다. 쿠버네티스는 컨테이너 런타임을 직접 대체하는 것이 아니라, 컨테이너 런타임을 제어하는 상위 관리자 역할을 수행한다.

컨테이너 런타임을 도커 <-> containerD로 바꾼다면

쿠버네티스 환경에서는 과거에 Docker를 컨테이너 런타임으로 사용했지만, 현재는 containerd나 CRI-O를 직접 사용하는 방식이 표준이 되었다.

이때 흔히 드는 의문이 있었다.

"컨테이너 런타임을 바꾸면 이미지도 다시 만들어야 하지 않을까?"

결론부터 말하면 그럴 필요가 없다.

OCI(Open Container Initiative)

그 이유는 OCI(Open Container Initiative) 표준 때문이다. OCI는 컨테이너 이미지 형식과 런타임 동작 방식에 대한 표준을 정의하는 단체이다.

• Docker 이미지
• containerd 이미지
• CRI-O 이미지

이들은 모두 OCI 표준을 따르기 때문에 서로 호환된다.

실제로 containerd 내부에서도 Docker에서 사용하던 runC를 그대로 사용한다.

즉, 컨테이너 런타임을 Docker에서 containerd로 변경하더라도 기존에 만들어 둔 이미지 변경 없이 그대로 사용 가능하다.

이 구조 덕분에 쿠버네티스는 특정 런타임에 종속되지 않고 유연하게 런타임을 교체할 수 있는 것이다.

요약

• 리눅스는 Debian 계열과 Red Hat 계열로 나뉜다.
• 기업 환경에서는 안정성과 표준화 때문에 Red Hat 계열(Rocky Linux)을 선호한다.
• Docker는 컨테이너 런타임을 포함한 플랫폼이다.
• 쿠버네티스는 컨테이너 런타임을 지휘하는 오케스트레이터이다.
• OCI 표준 덕분에 런타임을 바꿔도 이미지는 그대로 사용 가능하다.

위 포스팅은 인프런 강의 중 쿠버네티스 어나더 클래스-Sprint 1, 2를 참고하여 작성하였습니다.

API Server 요청 지표 확인

우선, 데이터가 정상적으로 수집되고 있는지를 확인하기 위해 Prometheus 쿼리를 먼저 실행한다.

apiserver_request_duration_seconds_bucket

이 쿼리는 Kubernetes API Server가 요청을 처리하는 데 걸린 시간을 버킷(bucket) 단위로 누적 카운트한 히스토그램 메트릭이다. 그래프가 정상적으로 출력된다면, Prometheus에서 해당 메트릭을 문제없이 수집 중이라는 의미다.

histogram_quantile 사용

Grafana의 suggestion에 표시된 쿼리를 클릭해 다음 쿼리를 실행한다.

histogram_quantile(0.95, sum by(le) (rate(apiserver_request_duration_seconds_bucket[$__rate_interval])))

이 쿼리의 의미는 다음과 같다.

• rate(...) → 히스토그램 버킷 값의 초당 증가율을 계산한다.

• sum by(le) → 여러 시계열을 le(less than or equal) 버킷 기준으로 합친다.

• histogram_quantile(0.95, ...) → 95퍼센타일(95% 요청이 이 값 이하로 처리됨) 을 계산한다.

즉, “최근 구간에서 API 요청의 95%가 이 시간 이내로 처리된다” 라는 값을 시계열로 보여주는 쿼리다.

실행하면 다음과 같이 표 형태의 결과가 출력된다.

조회 시간을 1분 단위로 변경

기본 $__rate_interval 대신, 고정된 1분 기준으로 보고 싶어서 다음과 같이 수정한다.

histogram_quantile(0.95, sum by(le) (rate(apiserver_request_duration_seconds_bucket[1m])))

이렇게 하면 1분 단위로 계산된 API Server 요청 지연 시간의 95퍼센타일 값을 확인할 수 있다.

특정 요청 타입(GET)만 필터링

이번에는 모든 요청이 아니라, GET 요청만 대상으로 분석해본다.

histogram_quantile(0.95, rate(apiserver_request_duration_seconds_bucket{verb="GET"}[1m]))

여기서 {verb="GET"} 은 아래와 같이 apiserver_request_duration_seconds_bucket 메트릭에 포함된 레이블을 기반으로 필터링한 것이다.

apiserver_request_duration_seconds_bucket

즉, API Server로 들어오는 GET 요청의 처리 시간 분포만 따로 분석하게 된다.

그래프가 직관적이지 않은 이유

이 상태로 Grafana에서 조회하면 다음과 같이 그래프가 출력된다.

하지만 이 그래프는

시간에 따른 값 변화는 보이지만, 요청 지연 시간 분포를 한눈에 파악하기는 어렵다

그래서 여기서 Visualization을 Histogram으로 변경한다.

Histogram 시각화 적용

Visualization에서 Histogram을 선택하면 다음과 같이 변경된다.

그러면 이와 같이 히스토그램으로 변경된 것을 확인할 수 있으며, API 서버의 요청 시간에 따른 각 구간의 빈도수를 시각적으로 효과적으로 확인할 수 있게 된다.

단위 및 임계값(Threshold) 설정

마지막으로 가독성을 높이기 위해 단위와 임계값을 설정한다.

• Unit → time / seconds 로 설정 → 요청 처리 시간이 초 단위라는 것을 명확히 표시

그리고 SRI / SLO 관점에서 임계값을 보기 위해 Threshold를 추가한다.

• Threshold 값: 0.05
• 색상: 빨간색

이렇게 설정하면 0.05초 이하 구간에 있는 요청들을 “문제가 있는 영역”으로 직관적으로 인지할 수 있다.

해당 게시물은 인프런 강의 중 "실습으로 배우는 그라파나"를 참고하여 작성하였습니다.

apiserver 요청에 대한 응답시간 (시간 흐름)을 Heatmap으로 나타내기

먼저 apiserver 요청 응답시간에 대한 히스토그램 메트릭이 수집되고 있는지 확인한다.

apiserver_request_duration_seconds_bucket

해당 메트릭을 쿼리하면 다음과 같이 응답시간 구간(bucket)별 데이터가 출력되는 것을 확인할 수 있다.

다음으로, 이 데이터를 Heatmap으로 표현하기 위해 가공한다. 히스토그램 메트릭은 누적 카운터 형태이기 때문에, 일정 시간 단위의 변화량을 보기 위해 rate 함수를 사용한다. 또한 응답시간 구간별 분포를 보기 위해 le 라벨 기준으로 그룹화하고, 나머지 라벨은 모두 합산한다.

최종적으로 사용하는 쿼리는 다음과 같다.

sum by(le) (rate(apiserver_request_duration_seconds_bucket[1m]))

이 쿼리는 최근 1분 동안 apiserver 요청이 각 응답시간 구간(le)에 얼마나 많이 발생했는지를 나타낸다.

해당 쿼리를 실행하면 아래와 같은 그래프가 표시된다.

하지만 이 상태에서는 시간대별로 어느 응답시간 구간에 요청이 몰렸는지를 직관적으로 파악하기 어렵다. 이를 개선하기 위해 패널 타입을 Heatmap으로 변경한다.

Heatmap으로 변경하면, 시간 흐름에 따라 특정 응답시간 구간에 요청이 집중되는 패턴을 색상으로 한눈에 확인할 수 있다.

추가로, Y축이 bucket 값(le) 그대로 표시되면 해석이 다소 어려울 수 있다. 이를 응답시간 단위로 명확히 표현하기 위해 Y축 설정에서 Time → Second로 변경한다.

이렇게 설정하면 Y축이 초 단위 응답시간으로 표시되어, 느린 요청이 어느 시간대에 발생했는지를 더욱 직관적으로 파악할 수 있다.

해당 게시물은 인프런 강의 중 "실습으로 배우는 그라파나"를 참고하여 작성하였습니다.