바이너리

"구글로 로그인"은 어떻게 동작할까?

BinaryNumber — Mon, 18 May 2026 22:36:23 +0900

"구글로 로그인"은 어떻게 동작할까? — OIDC 동작 원리

들어가며

"카카오로 로그인", "구글로 로그인" — 요즘 웹서비스에서 정말 흔하게 보이는 버튼이죠.

그런데 이 버튼을 누르면 내 뒤에서 무슨 일이 벌어지는 걸까요? 내 비밀번호를 그 서비스가 알게 되는 건 아닐까요?

그 비밀을 풀어주는 게 바로 OIDC(OpenID Connect)입니다.

먼저, OAuth 2.0을 알아야 해요

OIDC를 이해하려면 먼저 OAuth 2.0을 짚고 넘어가야 합니다.

OAuth 2.0은 "내 비밀번호를 알려주지 않고도, 특정 권한을 다른 서비스에게 위임"하는 프로토콜이에요.

예시를 들어볼게요.

어떤 앱이 "내 구글 드라이브 파일을 읽고 싶다"고 해요.

이때 내 구글 계정 비밀번호를 그 앱에 알려줄 순 없잖아요.

OAuth 2.0은 구글이 "이 앱은 드라이브 파일을 읽을 수 있다"는 허락증(Access Token)을 대신 발급해줍니다.

근데 여기서 문제가 생겼어요.

OAuth 2.0은 "권한 위임"에 집중하다 보니, "이 사용자가 누구인가"를 표준으로 정의하지 않았어요.

그래서 서비스마다 사용자 정보를 가져오는 방식이 제각각이었죠.

이 문제를 해결하기 위해 OAuth 2.0 위에 "사용자 인증" 기능을 표준으로 얹은 것이 바로 OIDC입니다.

OIDC의 등장인물

OIDC에는 3명의 주인공이 있어요.

역할	이름	실제 예시
사용자	End User	나 (로그인하는 사람)
내 정보를 관리하는 곳	Identity Provider (IdP)	구글, 카카오, 네이버
로그인을 요청하는 서비스	Relying Party (RP)	쇼핑몰, 블로그, 회사 앱

핵심은 이거예요.

내 비밀번호는 IdP(구글)만 알고, RP(쇼핑몰)는 절대 알 수 없다.

OIDC 흐름 한눈에 보기

아래는 "구글로 로그인" 버튼을 눌렀을 때 실제로 일어나는 일이에요.

sequenceDiagram actor 나 participant 쇼핑몰 participant 구글 나->>쇼핑몰: 로그인 버튼 클릭 쇼핑몰->>구글: 인증 요청 (client_id, scope=openid ...) 구글-->>나: 구글 로그인 화면 표시 나->>구글: ID/PW 입력 + 권한 허용 구글-->>나: 쇼핑몰로 리다이렉트 (code 전달) 나->>쇼핑몰: code 도착 쇼핑몰->>구글: code로 토큰 요청 (서버↔서버) 구글-->>쇼핑몰: ID Token + Access Token 발급 쇼핑몰-->>나: 로그인 완료!

단계별로 차근차근 살펴봅시다.

단계 1 — 인증 요청 (Authorization Request)

쇼핑몰이 구글에게 이렇게 요청해요.

https://accounts.google.com/o/oauth2/auth
  ?client_id=쇼핑몰_ID
  &redirect_uri=https://shop.example.com/callback
  &response_type=code
  &scope=openid email profile
  &state=abc123

주요 파라미터를 해석하면:

client_id : 쇼핑몰이 구글에 등록된 ID
redirect_uri : 로그인 후 사용자를 어디로 보낼지
scope=openid : "OIDC를 쓸게요" 라는 선언. 이게 있어야 OIDC예요
scope=email profile : 이메일, 이름도 알고 싶어요
state : 나중에 위조 요청 방어에 쓰는 랜덤 값

단계 2 — 사용자 로그인

구글 로그인 화면이 뜨고, 사용자가 아이디/비밀번호를 입력해요.

구글은 인증에 성공하면 이런 화면을 보여줄 수도 있어요.

"쇼핑몰이 이메일과 이름을 요청합니다. 허용하시겠어요?"

단계 3 — Authorization Code 전달

사용자가 허락하면, 구글은 아까 쇼핑몰이 알려준 redirect_uri로 사용자를 보내요.

https://shop.example.com/callback
  ?code=4/P7q7W91a
  &state=abc123

여기서 code는 일회용 코드예요. 그 자체로는 아무것도 아니고, 토큰으로 교환해야 비로소 의미가 생겨요.

단계 4 — 토큰 발급 (Token Exchange)

쇼핑몰 서버는 이 code를 가지고 구글에게 직접 토큰을 요청해요.

POST https://oauth2.googleapis.com/token

code          = 4/P7q7W91a
client_id     = 쇼핑몰_ID
client_secret = 쇼핑몰_비밀키
redirect_uri  = https://shop.example.com/callback
grant_type    = authorization_code

이 요청은 브라우저가 아니라 서버끼리 직접 이루어지기 때문에, 사용자가 볼 수 없어요.

구글은 이에 응답으로 두 가지 토큰을 줘요.

{
  "access_token": "ya29.xxx",
  "id_token":     "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

OIDC의 핵심 — ID Token

OIDC에서 가장 중요한 것은 바로 ID Token이에요.

access_token이 "이 사람이 어떤 걸 할 수 있다"는 허가증이라면,
id_token은 "이 사람이 누구다"를 증명하는 신분증이에요.

ID Token은 JWT(JSON Web Token) 형식이에요. 점(.)으로 구분된 세 파트로 이루어져 있어요.

# 헤더 — 어떤 알고리즘으로 서명했는지
eyJhbGciOiJSUzI1NiJ9

# 페이로드 — 실제 사용자 정보 (Claims)
eyJzdWIiOiIxMjM0NTY3ODkwIn0

# 서명 — 위조 방지
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

페이로드를 Base64로 디코딩하면 이런 정보가 나와요.

{
  "iss":   "https://accounts.google.com",  // 발급자 (구글)
  "sub":   "1234567890",                  // 사용자 고유 ID
  "aud":   "쇼핑몰_ID",                   // 이 토큰을 받을 대상
  "exp":   1716153600,                    // 만료 시간
  "iat":   1716150000,                    // 발급 시간
  "email": "user@example.com",
  "name":  "홍길동"
}

이 정보들을 Claims라고 불러요.

서명은 왜 중요한가요?

ID Token의 세 번째 파트인 서명 덕분에, 쇼핑몰은 이 토큰이 진짜 구글이 발급했는지 검증할 수 있어요.

구글은 자신의 공개 키를 공개해 두는데, 쇼핑몰은 이 키로 서명을 확인해요.

누군가 토큰 내용을 살짝 바꾼다면? → 서명이 맞지 않아서 즉시 탄로나요.

이 덕분에 쇼핑몰이 직접 사용자 정보 DB를 가지지 않아도, 구글이 "이 사람 맞아요"라고 보증해주는 구조가 만들어져요.

정리 — OIDC가 해결한 것

문제	OIDC의 해결책
내 비밀번호를 서비스에 알려줘야 하나?	비밀번호는 IdP(구글)에만 입력, 서비스는 절대 모름
서비스마다 사용자 정보 가져오는 방식이 다름	ID Token이라는 표준 형식으로 통일
토큰이 위조될 수 있지 않나?	JWT 서명으로 위조 즉시 탐지
"이 사람이 누구야?"를 어떻게 알아?	`sub` claim이 사용자 고유 식별자 역할

마치며

"구글로 로그인"은 단순해 보이지만, 뒤에서는 꽤 정교한 흐름이 돌아가고 있어요.

핵심만 기억하세요.

내 비밀번호는 구글만 알고, 다른 서비스는 절대 모른다
구글은 ID Token(신분증)을 발급해서 "이 사람 맞아요"를 보증해준다
ID Token은 JWT 형식이라 위조가 불가능하다

이 세 가지만 이해해도 OIDC의 절반은 이해한 거예요.

AWS Load Balancer Controller, Pod Identity로 설치하기

BinaryNumber — Sun, 17 May 2026 20:34:37 +0900

들어가며

EKS에서 Ingress를 쓰려면 AWS Load Balancer Controller가 필요합니다. 그리고 Controller가 ALB를 만들려면 IAM 권한이 있어야 해요.

이 글에서는 기존 IRSA(OIDC) 방식 대신 EKS Pod Identity를 사용해 권한을 연결하는 방법을 다룹니다.

Ingress Controller가 뭔가요?

Ingress Controller는 AWS 리소스(ALB)와 Kubernetes 사이의 중개 역할을 하는 컴포넌트입니다.

Ingress 리소스를 배포해도 Controller가 없으면 AWS 콘솔에 아무것도 생기지 않아요. 클러스터 생성 시 자동으로 설치되지 않기 때문에 직접 설치해야 합니다.

Controller가 하는 일:

역할	설명
이벤트 감시	API 서버로부터 Ingress 관련 이벤트를 감시하고 AWS 리소스 생성
ALB 생성	Ingress 1개당 ALB 1개 생성, Internet-facing / Internal 선택 가능
Target Group	Kubernetes 서비스 단위로 생성
Listener	포트 미지정 시 80/443으로 생성
Rule	Ingress에 정의한 경로 규칙대로 생성

EKS Pod Identity — IRSA 없이 IAM 권한 연결하기

Pod Identity는 Pod가 IAM 역할을 직접 부여받아 AWS 리소스에 접근하는 인증 방식입니다.

기존 IRSA와의 차이점:

항목	IRSA (기존)	Pod Identity
OIDC 공급자 등록	필요	불필요
ServiceAccount 어노테이션	필요	불필요
IAM 신뢰 정책 Principal	OIDC Provider ARN	`pods.eks.amazonaws.com`
추가 컴포넌트	없음	Pod Identity Agent 애드온 필요

동작 흐름:

Pod 실행
  → Pod Identity Agent가 임시 자격증명 요청
  → EKS가 연결된 IAM 역할 기반으로 자격증명 발급
  → Pod 내 AWS SDK가 자격증명 자동 사용

1. Pod Identity Agent 애드온 설치

Pod Identity를 사용하려면 클러스터에 EKS Pod Identity Agent 애드온이 먼저 설치되어 있어야 합니다.

aws eks create-addon \
    --cluster-name {Cluster Name} \
    --addon-name eks-pod-identity-agent \
    --region ap-northeast-2

설치 완료 여부를 확인합니다.

aws eks describe-addon \
    --cluster-name {Cluster Name} \
    --addon-name eks-pod-identity-agent \
    --region ap-northeast-2 \
    --query "addon.status"

"ACTIVE"가 출력되면 준비 완료입니다.

2. IAM 정책 생성

ALB를 생성·수정할 수 있는 IAM 정책을 만듭니다.

# 정책 파일 다운로드
curl -o iam_policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v3.0.0/docs/install/iam_policy.json

# 정책 생성
aws iam create-policy \
    --policy-name AWSLoadBalancerControllerIAMPolicy \
    --policy-document file://iam_policy.json

생성 후 출력되는 Policy.Arn 값을 메모해 두세요. 이후 단계에서 사용합니다.

3. Pod Identity용 IAM 역할 생성

Pod Identity에서는 pods.eks.amazonaws.com을 신뢰하는 IAM 역할을 만들어야 합니다.

아래 내용으로 trust-policy.json을 생성합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "pods.eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

역할을 생성하고 앞서 만든 정책을 연결합니다.

# 역할 생성
aws iam create-role \
    --role-name AWSLoadBalancerControllerRole \
    --assume-role-policy-document file://trust-policy.json

# 정책 연결
aws iam attach-role-policy \
    --role-name AWSLoadBalancerControllerRole \
    --policy-arn {Policy ARN}

4. Pod Identity Association 생성

IAM 역할과 Kubernetes ServiceAccount를 연결합니다.

aws eks create-pod-identity-association \
    --cluster-name {Cluster Name} \
    --namespace kube-system \
    --service-account aws-load-balancer-controller \
    --role-arn {Role ARN} \
    --region ap-northeast-2

5. ServiceAccount 생성

Pod Identity에서는 ServiceAccount에 어노테이션이 필요 없습니다. 이름만 맞춰서 생성하면 됩니다.

kubectl create serviceaccount aws-load-balancer-controller \
    -n kube-system

6. AWS Load Balancer Controller 설치

Helm으로 설치합니다. Helm이 없다면 먼저 설치해주세요.

curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

EKS Helm 레포지토리를 추가합니다.

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

Controller를 설치합니다.

helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
    -n kube-system \
    --set clusterName={Cluster Name} \
    --set serviceAccount.create=false \
    --set serviceAccount.name=aws-load-balancer-controller \
    --set image.repository=602401143452.dkr.ecr.ap-northeast-2.amazonaws.com/amazon/aws-load-balancer-controller \
    --set region=ap-northeast-2 \
    --set vpcId={VPC ID}

정상 설치 여부를 확인합니다.

kubectl get deployment -n kube-system aws-load-balancer-controller

7. Ingress 생성해보기

2048 게임 예제로 Ingress가 잘 동작하는지 확인할 수 있습니다.

# 생성
kubectl apply -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.11.0/docs/examples/2048/2048_full.yaml

# 삭제
kubectl delete -f https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/v2.11.0/docs/examples/2048/2048_full.yaml

HTTPS는 어떻게 안전한 걸까?

BinaryNumber — Sun, 17 May 2026 13:59:56 +0900

TLS 인증서 파헤치기

들어가며

브라우저 주소창에 자물쇠 아이콘이 뜨면 "안전하다"고 느끼죠. 그런데 그게 왜 안전한 건지 설명할 수 있나요?

그 핵심에 TLS 인증서가 있습니다. 이 글에서는 TLS가 뭔지, 인증서가 어떻게 신뢰를 만들어내는지를 최대한 쉽게 풀어봅니다.

TLS가 뭔가요? SSL이랑 다른 건가요?

TLS(Transport Layer Security)는 네트워크 통신을 암호화하는 프로토콜입니다. SSL(Secure Sockets Layer)의 후속 버전인데, SSL이라는 이름이 워낙 익숙해져서 지금도 혼용해서 부르는 경우가 많아요.

정리하면:

SSL → 오래된 버전, 현재는 보안 취약점으로 사용 안 함
TLS 1.2 → 현재도 널리 쓰임
TLS 1.3 → 최신 버전, 더 빠르고 안전함

"SSL 인증서 발급받으세요"라고 하면 실제로는 TLS 인증서를 말하는 겁니다.

TLS가 해주는 세 가지

TLS는 크게 세 가지를 보장합니다.

암호화 (Encryption)

주고받는 데이터를 제3자가 볼 수 없도록 암호화합니다. 카페 와이파이에서 누군가 패킷을 가로채도 내용을 읽을 수 없어요.

인증 (Authentication)

지금 연결한 서버가 진짜 그 서버인지 확인합니다. 피싱 사이트가 naver.com인 척 흉내 내도, 인증서가 없으면 브라우저가 경고를 띄웁니다.

무결성 (Integrity)

전송 중에 데이터가 변조되지 않았음을 보장합니다. 중간에서 누군가 내용을 슬쩍 바꿔도 감지할 수 있어요.

인증서란 무엇인가요?

인증서는 쉽게 말해 "이 서버는 믿어도 됩니다"라는 공인된 신분증입니다.

인증서 안에는 이런 정보가 들어 있어요:

도메인 이름 (예: example.com)
공개 키 (public key)
발급자 (인증 기관, CA)
유효 기간
디지털 서명

브라우저는 서버에 접속할 때 이 인증서를 받아서 "이게 진짜인지" 검증합니다.

CA가 뭔데 믿을 수 있는 거예요?

CA(Certificate Authority, 인증 기관)는 인증서를 발급하고 서명하는 기관입니다. DigiCert, Let's Encrypt, Comodo 같은 곳들이에요.

브라우저(크롬, 파이어폭스 등)와 OS(윈도우, 맥 등)에는 신뢰하는 CA 목록이 미리 내장돼 있습니다. 이걸 루트 CA 스토어라고 해요.

흐름을 따라가면:

서버 운영자가 CA에 인증서 발급 신청
CA가 도메인 소유권 등을 검증
CA가 자신의 개인 키로 인증서에 서명 발급
브라우저가 인증서를 받아서 CA의 공개 키로 서명 검증
서명이 유효하면 → 신뢰할 수 있는 서버로 간주

즉, CA를 신뢰하기 때문에 CA가 서명한 인증서도 신뢰하는 구조입니다.

인증서 체인 (Certificate Chain)

인증서는 보통 혼자 존재하지 않고 체인을 이룹니다.

루트 CA (Root CA)
  └── 중간 CA (Intermediate CA)
        └── 서버 인증서 (End-entity Certificate)

루트 CA가 직접 모든 인증서에 서명하지 않고, 중간 CA에 권한을 위임합니다. 루트 CA의 개인 키는 오프라인에 보관할 정도로 중요하게 취급해요.

브라우저가 서버 인증서를 받으면, 체인을 따라 루트 CA까지 거슬러 올라가며 검증합니다. 체인이 끊기거나 루트 CA가 신뢰 목록에 없으면 경고가 뜨는 거예요.

TLS 핸드셰이크 — 연결이 맺어지는 과정

TLS 1.2 — 기본 흐름 (2-RTT)

브라우저와 서버가 처음 연결할 때 왕복 2회가 필요합니다.

클라이언트              서버
    │                    │
    │── ClientHello ────►│  1) TLS 버전, 암호화 방식 제안
    │                    │
    │◄─ ServerHello ─────│  2) 암호화 방식 결정 + 인증서 전달
    │   + 인증서           │
    │                    │
    │   [인증서 검증]       │
    │                    │
    │── 키 교환 ─────────► │  3) 공개 키로 암호화된 프리마스터 시크릿 전달
    │                    │
    │◄─ Finished ────────│  4) 핸드셰이크 완료
    │                    │
    │══ 암호화 통신 시작 ══  │

핵심은 세션 키(대칭 키) 를 안전하게 교환하는 과정입니다. 이 세션 키로 이후 모든 데이터를 암호화해요.

TLS 1.3 — 더 빠르고 단순해진 과정 (1-RTT)

TLS 1.3은 ClientHello에 키 교환 정보(key_share)를 함께 보내서 왕복을 1회로 줄였습니다.

key_share란?
ECDHE 키 교환에서 클라이언트가 미리 생성한 임시 공개 키입니다.
클라이언트는 연결 시작 전에 임시 키 쌍(공개 키 + 개인 키)을 만들어두고, 공개 키만 key_share에 담아 보냅니다.
서버도 자신의 임시 키 쌍을 만들어 응답에 공개 키를 담아 보내면,
양쪽이 상대방의 공개 키와 자신의 개인 키를 조합해 동일한 세션 키를 독립적으로 계산합니다.
세션 키 자체는 네트워크로 전송되지 않으므로 가로챌 수 없습니다.

클라이언트              서버
    │                    │
    │── ClientHello ────►│  1) TLS 버전 + key_share 동시 전송
    │   + key_share      │
    │                    │
    │◄─ ServerHello ─────│  2) {인증서 + Finished} 암호화해서 전달
    │   + {인증서}         │     (이미 세션 키 생성 완료)
    │   + {Finished}     │
    │                    │
    │── {Finished} ── ──►│  3) 확인 완료
    │                    │
    │══ 암호화 통신 시작 ══│

{} 표시는 이미 암호화된 상태로 전송됨을 의미합니다. TLS 1.2보다 훨씬 일찍 암호화가 시작돼요.

0-RTT 재연결 — 이전에 접속한 적 있다면

같은 서버에 재연결할 때는 이전 세션의 키를 재활용해 첫 패킷부터 데이터를 보낼 수 있습니다.

클라이언트              서버
    │                    │
    │── ClientHello ────►│
    │   + 0-RTT 데이터     │  연결과 동시에 요청 전송
    │                    │
    │◄─ ServerHello ─────│
    │   + {응답}          │
    │                    │
    │ ══ 암호화 통신 시작 ══ │

단, 0-RTT는 재전송 공격(Replay Attack) 위험이 있어서 멱등성이 없는 요청(예: 결제)에는 사용하지 않는 게 좋습니다.

멱등성(Idempotency)이란?
같은 요청을 여러 번 보내도 결과가 똑같은 성질을 말합니다.

멱등성 있음: GET /users/1 (몇 번 요청해도 같은 데이터)
             DELETE /users/1 (이미 삭제된 걸 또 삭제해도 결과 동일)
멱등성 없음: POST /orders (요청이 2번 전송되면 주문이 2개 생김)
             POST /payments (중복 결제 발생)

공격자가 캡처한 0-RTT 패킷을 재전송하면 멱등성 없는 요청은 의도치 않게 두 번 실행될 수 있습니다.

TLS 1.2 vs 1.3 비교

항목	TLS 1.2	TLS 1.3
핸드셰이크 왕복	2-RTT	1-RTT
재연결	1-RTT	0-RTT 가능
키 교환 방식	RSA 또는 DH	ECDHE 필수 (전방향 비밀성 보장)
암호화 시작 시점	Finished 이후	ServerHello 직후
지원 암호화 방식	다양 (취약한 것 포함)	5가지로 제한, 강한 것만

키 교환 방식이란?

클라이언트와 서버가 세션 키를 안전하게 공유하는 방법입니다. 세션 키 자체를 네트워크로 직접 보내면 가로챌 수 있기 때문에, 수학적 방법으로 양쪽이 같은 키를 독립적으로 계산해냅니다.

방식	설명
RSA	클라이언트가 서버의 공개 키로 암호화해서 세션 키 전송
DH (Diffie-Hellman)	양쪽이 각자 난수를 만들어 수학적으로 같은 값을 도출
ECDHE	DH의 타원곡선 버전, 매 연결마다 새 키 쌍 생성 (TLS 1.3 필수)

ECDHE의 핵심은 전방향 비밀성(Forward Secrecy) 입니다. 매 연결마다 임시 키를 새로 만들기 때문에, 나중에 서버의 개인 키가 유출되더라도 과거 통신 내용은 해독할 수 없어요.

인증서 종류 — 뭐가 다를까요?

도메인 기준

종류	설명
단일 도메인	`example.com` 하나만 커버
와일드카드	`*.example.com` — 서브도메인 전체 커버
멀티 도메인(SAN)	여러 도메인을 하나의 인증서로 커버

검증 수준 기준

종류	검증 내용	발급 속도
DV (Domain Validation)	도메인 소유권만 확인	수 분 ~ 즉시
OV (Organization Validation)	도메인 + 조직 실체 확인	수 일
EV (Extended Validation)	도메인 + 조직 법적 실체 엄격 확인	수 주

일반 서비스라면 DV로 충분합니다. Let's Encrypt도 DV 인증서를 발급해줘요.

자주 마주치는 인증서 오류들

`NET::ERR_CERT_AUTHORITY_INVALID`

인증서를 발급한 CA가 브라우저 신뢰 목록에 없을 때. 자체 서명 인증서(self-signed)나 사설 CA 사용 시 발생합니다.

`NET::ERR_CERT_DATE_INVALID`

인증서 유효 기간이 만료됐을 때. 갱신을 깜빡하면 바로 서비스 장애로 이어집니다.

`NET::ERR_CERT_COMMON_NAME_INVALID`

인증서의 도메인과 실제 접속한 도메인이 다를 때. www.example.com 인증서로 example.com에 접속하면 뜰 수 있어요.

`SSL_ERROR_RX_RECORD_TOO_LONG`

HTTP 포트(80)로 HTTPS 요청이 들어왔을 때 종종 발생합니다. 서버 설정 문제예요.

인증서 관련 자주 쓰는 명령어

# 서버 인증서 정보 확인
openssl s_client -connect example.com:443 -showcerts

# 인증서 파일 내용 확인
openssl x509 -in cert.pem -text -noout

# 만료일만 확인
openssl x509 -in cert.pem -noout -enddate

# CSR (인증서 서명 요청) 생성
openssl req -new -newkey rsa:2048 -nodes \
  -keyout server.key \
  -out server.csr

# 개인 키와 인증서로 만료일 확인 (원격)
echo | openssl s_client -connect example.com:443 2>/dev/null \
  | openssl x509 -noout -dates

마치며

TLS 인증서는 단순히 "자물쇠 아이콘"이 아니라, 암호화·인증·무결성을 한 번에 보장하는 핵심 보안 인프라입니다.

구조를 이해하면 인증서 오류가 왜 뜨는지, 어떻게 해결해야 하는지 훨씬 빠르게 파악할 수 있어요. 다음 번에 브라우저 경고가 뜨면 막연히 "위험하다"가 아니라 어디서 체인이 끊겼는지 찾아보세요.

Helm upgrade

BinaryNumber — Sun, 17 May 2026 13:28:52 +0900

Helm upgrade, 이것만 알면 됩니다

들어가며

Helm은 Kubernetes 패키지 매니저로, helm upgrade 명령을 통해 배포된 애플리케이션을 업데이트합니다.

시작 전에 확인할 것들

# 현재 설치된 릴리스 목록 확인
helm list -n <namespace>

# 릴리스의 현재 values 확인
helm get values <release-name> -n <namespace>

# 현재 사용 중인 차트 버전 확인
helm get chart <release-name> -n <namespace>

이미지 태그만 바꾸고 싶을 때

차트 버전은 그대로 두고 컨테이너 이미지만 교체할 때 사용합니다.

helm upgrade <release-name> <chart> \
  -n <namespace> \
  --reuse-values \
  --set image.tag=<new-tag>

--reuse-values: 기존 values를 그대로 유지하면서 지정한 값만 덮어씁니다.

설정 여러 개를 한 번에 바꾸려면

변경 사항이 여러 개일 때는 values 파일을 수정한 후 적용합니다.

# values.yaml 수정 후
helm upgrade <release-name> <chart> \
  -n <namespace> \
  -f values.yaml

여러 values 파일을 겹쳐 쓸 수도 있습니다 (뒤에 오는 파일이 우선).

helm upgrade <release-name> <chart> \
  -n <namespace> \
  -f values-base.yaml \
  -f values-prod.yaml

차트 버전 자체를 올려야 할 때

차트 자체의 버전을 올릴 때 사용합니다.

# 최신 차트 정보 가져오기
helm repo update

# 사용 가능한 버전 확인
helm search repo <chart-name> --versions

# 특정 버전으로 업그레이드
helm upgrade <release-name> <repo>/<chart-name> \
  -n <namespace> \
  --version <chart-version> \
  -f values.yaml

적용 전에 뭐가 바뀌는지 먼저 보는 법

실제 적용 전에 무엇이 바뀌는지 확인합니다. helm-diff 플러그인이 필요합니다.

# helm-diff 플러그인 설치 (최초 1회)
helm plugin install https://github.com/databus23/helm-diff

# 변경 사항 미리 보기
helm diff upgrade <release-name> <chart> \
  -n <namespace> \
  -f values.yaml

--dry-run으로 렌더링된 매니페스트만 확인할 수도 있습니다.

helm upgrade <release-name> <chart> \
  -n <namespace> \
  -f values.yaml \
  --dry-run

업데이트하고 나서 꼭 확인할 것들

# 릴리스 상태 확인
helm status <release-name> -n <namespace>

# 히스토리 확인
helm history <release-name> -n <namespace>

# Pod 상태 확인
kubectl get pods -n <namespace>

# 롤아웃 완료 대기
kubectl rollout status deployment/<deployment-name> -n <namespace>

뭔가 잘못됐다면? 롤백하면 됩니다

업데이트 후 문제가 생기면 이전 리비전으로 되돌립니다.

# 히스토리에서 롤백할 리비전 번호 확인
helm history <release-name> -n <namespace>

# 직전 버전으로 롤백
helm rollback <release-name> -n <namespace>

# 특정 리비전으로 롤백
helm rollback <release-name> <revision> -n <namespace>

알아두면 유용한 옵션 모음

옵션	설명
`--reuse-values`	기존 values 유지, 지정한 값만 덮어씀
`--reset-values`	values를 차트 기본값으로 초기화
`--set key=value`	개별 값 지정
`-f values.yaml`	values 파일 지정
`--version`	차트 버전 고정
`--atomic`	실패 시 자동 롤백
`--timeout`	대기 시간 설정 (기본 5m)
`--dry-run`	실제 적용 없이 렌더링 결과만 출력

배포 전 체크리스트 — 이것만은 꼭

현재 values 백업: helm get values <release-name> -n <namespace> > values-backup.yaml
--dry-run 또는 helm diff로 변경 사항 사전 확인
업데이트 전 현재 리비전 번호 메모 (helm history)
업데이트 후 Pod 상태 및 로그 확인
문제 발생 시 즉시 helm rollback 실행

ArgoCD Notifications Slack 연동

BinaryNumber — Sat, 16 May 2026 16:29:29 +0900

GitOps / ArgoCD 시리즈

1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리
2편 — ArgoCD Application, AppProject 개념 정리
3편 — ApplicationSet으로 멀티 클러스터 배포 자동화
4편 — ArgoCD Notifications Slack 연동 가이드 (현재 글)

ArgoCD는 기본적으로 배포 결과를 알려주지 않습니다. argocd-notifications-controller를 설정하면 Sync 성공/실패, Health 상태 변화를 Slack으로 받을 수 있습니다. 이 글에서는 Slack Webhook 방식으로 알림을 설정하는 방법을 단계별로 정리합니다.

ArgoCD Notifications는 trigger(언제 알릴지) + template(어떻게 알릴지) + subscription(어디로 알릴지) 세 가지 조합으로 동작합니다.

동작 원리

[Application 상태 변화]
       │
       ▼
[trigger 조건 평가] ── 조건 불충족 → 무시
       │ 조건 충족
       ▼
[template으로 메시지 생성]
       │
       ▼
[subscription에 등록된 채널로 발송]
       │
       ▼
[Slack / Email / PagerDuty / ...]

설정 방법

Slack Webhook URL 발급

Slack 워크스페이스에서 앱 관리 → Incoming Webhooks → 새 Webhook 추가로 채널별 Webhook URL을 발급합니다.

URL 형식: https://hooks.slack.com/services/T.../B.../...

Webhook URL을 Secret으로 저장

kubectl create secret generic argocd-notifications-secret \
  --from-literal=slack-token=https://hooks.slack.com/services/T.../B.../... \
  -n argocd

또는 이미 Secret이 있다면 패치:

kubectl patch secret argocd-notifications-secret \
  -n argocd \
  -p '{"stringData": {"slack-token": "https://hooks.slack.com/services/..."}}'

values.yaml에 Notifications 설정 추가

Helm으로 설치했다면 values.yaml에 아래 설정을 추가하고 helm upgrade로 적용합니다.

notifications:
  enabled: true

  secret:
    create: false              # 위에서 직접 만든 Secret 사용

  cm:
    create: true

  # 발송 서비스 설정
  notifiers:
    service.slack: |
      token: $slack-token      # Secret의 slack-token 키 참조

  # Trigger: 언제 알릴지
  triggers:
    trigger.on-sync-succeeded: |
      - when: app.status.operationState.phase in ['Succeeded']
        send: [app-sync-succeeded]

    trigger.on-sync-failed: |
      - when: app.status.operationState.phase in ['Error', 'Failed']
        send: [app-sync-failed]

    trigger.on-health-degraded: |
      - when: app.status.health.status == 'Degraded'
        send: [app-health-degraded]

    trigger.on-deployed: |
      - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
        send: [app-deployed]

  # Template: 어떻게 알릴지
  templates:
    template.app-sync-succeeded: |
      slack:
        attachments: |
          [{
            "color": "#2eb67d",
            "title": "✅ Sync 성공: {{.app.metadata.name}}",
            "fields": [
              {"title": "환경", "value": "{{.app.spec.destination.server}}", "short": true},
              {"title": "Revision", "value": "{{.app.status.sync.revision}}", "short": true},
              {"title": "시각", "value": "{{.app.status.operationState.finishedAt}}", "short": false}
            ]
          }]

    template.app-sync-failed: |
      slack:
        attachments: |
          [{
            "color": "#e01e5a",
            "title": "❌ Sync 실패: {{.app.metadata.name}}",
            "fields": [
              {"title": "에러", "value": "{{.app.status.operationState.message}}", "short": false},
              {"title": "Revision", "value": "{{.app.status.sync.revision}}", "short": true}
            ]
          }]

    template.app-health-degraded: |
      slack:
        attachments: |
          [{
            "color": "#ff6b35",
            "title": "⚠️ Health Degraded: {{.app.metadata.name}}",
            "fields": [
              {"title": "상태", "value": "{{.app.status.health.status}}", "short": true},
              {"title": "Message", "value": "{{.app.status.health.message}}", "short": false}
            ]
          }]

    template.app-deployed: |
      slack:
        attachments: |
          [{
            "color": "#2eb67d",
            "title": "  배포 완료: {{.app.metadata.name}}",
            "fields": [
              {"title": "Namespace", "value": "{{.app.spec.destination.namespace}}", "short": true},
              {"title": "Revision", "value": "{{.app.status.sync.revision}}", "short": true}
            ]
          }]

  # 기본 Subscription: 모든 Application에 적용
  subscriptions: |
    - recipients:
        - slack:#devops-alerts    # 알림 받을 Slack 채널
      triggers:
        - on-sync-failed
        - on-health-degraded

Helm upgrade로 적용

helm upgrade argocd argo/argo-cd \
  -n argocd \
  -f values.yaml

Slack 알림 미리보기

위 template 설정을 적용하면 Slack에서 이렇게 보입니다.

✅ Sync 성공: my-app-production

환경 https://prod.example.com

Revision a1b2c3d

시각 2026-05-16T10:32:00Z

❌ Sync 실패: my-app-production

에러 Failed to create resource: namespaces "production" not found

Revision d4e5f6g

Application별 채널 분리 — Subscription 어노테이션

Helm values의 subscriptions는 전체 기본값입니다. 특정 Application에만 다른 채널로 알림을 보내려면 Application 매니페스트에 어노테이션을 추가합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
  annotations:
    # 이 Application은 별도 채널로 알림 수신
    notifications.argoproj.io/subscribe.on-sync-failed.slack: backend-alerts
    notifications.argoproj.io/subscribe.on-deployed.slack: backend-deploys
    notifications.argoproj.io/subscribe.on-health-degraded.slack: backend-alerts

ApplicationSet으로 생성하는 경우 template에 어노테이션을 추가합니다:

  template:
    metadata:
      name: "my-app-{{env}}"
      annotations:
        notifications.argoproj.io/subscribe.on-sync-failed.slack: "{{team}}-alerts"
        notifications.argoproj.io/subscribe.on-deployed.slack: "{{team}}-deploys"

Trigger 조건 커스터마이징

Trigger는 expr-lang 문법을 사용합니다. 주요 조건 예시입니다.

조건	설명
`app.status.operationState.phase in ['Succeeded']`	Sync 성공
`app.status.operationState.phase in ['Error', 'Failed']`	Sync 실패
`app.status.health.status == 'Degraded'`	Health Degraded
`app.status.health.status == 'Healthy'`	Health 정상
`app.metadata.labels['env'] == 'production'`	production 레이블 Application만
`time.Now().Sub(time.Parse(app.status.operationState.startedAt)).Minutes() >= 10`	Sync가 10분 이상 걸린 경우

운영 환경만 알림 받기

triggers:
  trigger.on-sync-failed: |
    - when: >
        app.status.operationState.phase in ['Error', 'Failed'] and
        app.metadata.labels['env'] == 'production'
      send: [app-sync-failed]

알림 동작 테스트

설정 후 실제로 알림이 가는지 CLI로 테스트할 수 있습니다.

# 특정 Application에 대해 알림 강제 발송 테스트
argocd admin notifications trigger run on-sync-failed my-app \
  --recipient slack:devops-alerts \
  -n argocd

# 현재 구독 목록 확인
argocd admin notifications service list -n argocd

자주 하는 실수

Secret 키 이름이 틀린 경우

service.slack에서 $slack-token으로 참조할 때, Secret의 키 이름이 정확히 slack-token이어야 합니다. 키 이름이 다르면 알림 컨트롤러 로그에 secret not found 에러가 납니다.

확인 명령: kubectl get secret argocd-notifications-secret -n argocd -o jsonpath='{.data}' | base64 -d

알림이 안 올 때 확인할 것

notifications-controller 파드 로그 확인: kubectl logs -n argocd -l app.kubernetes.io/name=argocd-notifications-controller
ConfigMap 확인: kubectl get cm argocd-notifications-cm -n argocd -o yaml
Application 어노테이션에 subscription이 제대로 달려있는지 확인
Slack Webhook URL이 유효한지 curl로 직접 테스트

알림 피로도 줄이기

기본 subscription에는 on-sync-failed와 on-health-degraded만 걸어두고, 성공 알림(on-deployed)은 팀 채널에만 선택적으로 구독하는 것을 권장합니다. 모든 Application의 Sync 성공 알림이 오면 알림 피로도가 높아집니다.

마치며

ArgoCD Notifications는 trigger + template + subscription 세 가지만 이해하면 충분히 원하는 형태로 커스터마이징할 수 있습니다. 처음에는 on-sync-failed와 on-health-degraded만 설정해서 시작하고, 필요에 따라 trigger와 채널을 추가해가는 것을 권장합니다.

시리즈 완결

1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리
2편 — ArgoCD Application, AppProject 개념 정리
3편 — ApplicationSet으로 멀티 클러스터 배포 자동화
4편 — ArgoCD Notifications Slack 연동 가이드

ArgoCD ApplicationSet

BinaryNumber — Sat, 16 May 2026 16:28:39 +0900

GitOps / ArgoCD 시리즈

1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리
2편 — ArgoCD Application, AppProject 개념 정리
3편 — ApplicationSet으로 멀티 클러스터 배포 자동화 (현재 글)
4편 — ArgoCD Notifications Slack 연동 가이드

Application을 하나씩 수동으로 만들다 보면 클러스터나 환경이 늘어날수록 관리가 힘들어집니다. ApplicationSet은 이 문제를 해결하는 ArgoCD의 자동화 리소스입니다. Generator가 만들어내는 파라미터 목록을 템플릿에 주입해서 Application을 자동으로 생성·삭제합니다.

ApplicationSet의 핵심 구조: Generator (파라미터 목록 생성) + Template (Application 템플릿) → Application 자동 생성

기본 구조

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-appset
  namespace: argocd
spec:
  generators:
    - list:                    # Generator: 파라미터 목록
        elements:
          - cluster: prod
            url: https://prod.example.com
          - cluster: staging
            url: https://staging.example.com

  template:                    # Template: Application 청사진
    metadata:
      name: "my-app-{{cluster}}"   # Generator 파라미터 사용
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "k8s/overlays/{{cluster}}"
      destination:
        server: "{{url}}"
        namespace: my-app

위 ApplicationSet은 my-app-prod와 my-app-staging 두 Application을 자동으로 생성합니다. 환경이 추가되면 elements에 항목만 추가하면 됩니다.

Generator 종류

List Generator

가장 단순

직접 작성한 값 목록으로 Application을 생성합니다. 환경 수가 적고 정적일 때 사용합니다.

Cluster Generator

멀티 클러스터 핵심

ArgoCD에 등록된 클러스터 목록을 자동으로 읽어서 파라미터를 생성합니다. 클러스터가 추가되면 Application도 자동으로 생성됩니다.

Git Generator

디렉토리 / 파일 기반

Git 레포의 디렉토리 구조나 JSON/YAML 파일을 읽어서 파라미터를 생성합니다. 디렉토리 하나 = Application 하나 패턴에 유용합니다.

Matrix / Merge Generator

조합 / 병합

두 Generator의 결과를 곱집합(Matrix)하거나 병합(Merge)해서 복잡한 파라미터 조합을 만듭니다. "모든 앱 × 모든 환경" 패턴에 사용합니다.

Cluster Generator — 멀티 클러스터 자동 배포

가장 많이 쓰는 패턴입니다. ArgoCD에 클러스터를 등록하면 자동으로 해당 클러스터에 Application이 생성됩니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: cluster-addons
  namespace: argocd
spec:
  generators:
    - clusters:
        selector:
          matchLabels:
            env: production    # 레이블로 대상 클러스터 필터링

  template:
    metadata:
      name: "cluster-addons-{{name}}"
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/cluster-addons
        targetRevision: main
        path: addons
      destination:
        server: "{{server}}"   # 클러스터 URL 자동 주입
        namespace: kube-system
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

클러스터를 ArgoCD에 등록하는 명령:

# ArgoCD CLI로 클러스터 등록
argocd cluster add my-prod-context --name prod-ap-northeast-2

# 레이블 추가 (Cluster Generator 필터링용)
kubectl label secret -n argocd \
  $(argocd cluster list -o json | jq -r '.[] | select(.name=="prod-ap-northeast-2") | .connectionState.attemptedAt' ) \
  env=production

Git Generator — 디렉토리 기반 자동 생성

Git 레포의 디렉토리 구조를 그대로 Application으로 매핑합니다. 새 서비스를 추가할 때 디렉토리만 만들면 Application이 자동 생성됩니다.

# 레포 구조 예시
apps/
├── frontend/
│   └── kustomization.yaml
├── backend-api/
│   └── kustomization.yaml
└── batch-worker/
    └── kustomization.yaml

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: apps-from-dirs
  namespace: argocd
spec:
  generators:
    - git:
        repoURL: https://github.com/my-org/my-repo
        revision: main
        directories:
          - path: apps/*        # apps/ 하위 모든 디렉토리

  template:
    metadata:
      name: "{{path.basename}}"    # 디렉토리 이름이 Application 이름
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "{{path}}"           # 해당 디렉토리 경로
      destination:
        server: https://kubernetes.default.svc
        namespace: "{{path.basename}}"
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

Matrix Generator — 앱 × 환경 조합

"모든 앱을 모든 환경에 배포"하는 패턴입니다. 앱 목록과 환경 목록의 곱집합으로 Application을 생성합니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: all-apps-all-envs
  namespace: argocd
spec:
  generators:
    - matrix:
        generators:
          # Generator 1: 앱 목록 (Git 디렉토리)
          - git:
              repoURL: https://github.com/my-org/my-repo
              revision: main
              directories:
                - path: apps/*

          # Generator 2: 환경 목록
          - list:
              elements:
                - env: staging
                  server: https://staging.example.com
                - env: production
                  server: https://prod.example.com

  template:
    metadata:
      name: "{{path.basename}}-{{env}}"
    spec:
      project: "{{env}}"
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: main
        path: "{{path}}/overlays/{{env}}"
      destination:
        server: "{{server}}"
        namespace: "{{path.basename}}"

PR 환경 자동화 — Pull Request Generator

PR이 열릴 때 임시 환경을 자동으로 만들고, PR이 닫히면 삭제하는 패턴입니다.

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: pr-preview
  namespace: argocd
spec:
  generators:
    - pullRequest:
        github:
          owner: my-org
          repo: my-repo
          tokenRef:
            secretName: github-token
            key: token
          labels:
            - preview              # 'preview' 레이블이 달린 PR만 대상

  template:
    metadata:
      name: "pr-{{number}}-preview"
    spec:
      project: default
      source:
        repoURL: https://github.com/my-org/my-repo
        targetRevision: "{{head_sha}}"    # PR의 최신 커밋
        path: k8s/overlays/preview
      destination:
        server: https://kubernetes.default.svc
        namespace: "pr-{{number}}"        # PR 번호별 namespace
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
        syncOptions:
          - CreateNamespace=true

syncPolicy.preserveResourcesOnDeletion

ApplicationSet이 삭제되거나 Generator에서 항목이 제거될 때, 생성된 Application과 그 리소스를 어떻게 처리할지 설정합니다.

spec:
  syncPolicy:
    preserveResourcesOnDeletion: true   # true: Application 삭제 시 클러스터 리소스 유지
                                        # false (기본): Application 삭제 시 리소스도 삭제

PR Generator 사용 시 주의

PR이 닫히면 namespace와 그 안의 모든 리소스가 삭제됩니다. preserveResourcesOnDeletion: true를 사용하면 리소스는 남기고 Application만 삭제합니다. 데이터가 중요한 서비스라면 반드시 확인하세요.

실무 팁

tempate.metadata.annotations으로 알림 연동

ApplicationSet으로 생성된 Application에도 Notifications 어노테이션을 템플릿에 추가하면 자동으로 알림이 붙습니다.

notifications.argoproj.io/subscribe.on-sync-failed.slack: devops-alerts

ignoreApplicationDifferences로 일부 필드 무시

ApplicationSet이 관리하지 않는 필드(예: 수동으로 추가한 어노테이션)가 있을 때 ApplicationSet이 계속 덮어쓰는 문제를 방지합니다.

spec:
  ignoreApplicationDifferences:
    - jsonPointers:
        - /spec/source/targetRevision   # 이미지 태그 등 별도 관리하는 필드 무시

마치며

ApplicationSet은 "Application을 어떻게 자동화할 것인가"의 답입니다. List Generator로 시작해서 Git Generator, Cluster Generator 순서로 익혀가면 자연스럽게 멀티 클러스터 GitOps 체계를 갖출 수 있습니다.

다음 편에서는 argocd-notifications-controller를 이용해 Slack 알림을 설정하는 방법을 다룹니다.

다음 편

4편 — ArgoCD Notifications Slack 연동 가이드

ArgoCD Application, AppProject

BinaryNumber — Sat, 16 May 2026 16:25:26 +0900

GitOps / ArgoCD 시리즈

1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리
2편 — ArgoCD Application, AppProject 개념 정리 (현재 글)
3편 — ApplicationSet으로 멀티 클러스터 배포 자동화
4편 — ArgoCD Notifications Slack 연동 가이드

ArgoCD를 처음 쓰면 Application과 AppProject가 헷갈립니다. 이 두 가지는 ArgoCD의 핵심 커스텀 리소스로, 이 개념을 잘 이해해야 멀티 팀 환경에서 ArgoCD를 제대로 운영할 수 있습니다.

이 글에서는 ArgoCD의 두 핵심 CRD인 Application과 AppProject의 역할과 관계, 그리고 실무에서 어떻게 구성하는지를 다룹니다.

Application — "무엇을 어디에 배포할 것인가"

Application은 ArgoCD에서 배포의 기본 단위입니다. Git 레포의 어느 경로에 있는 매니페스트를 어느 클러스터/네임스페이스에 배포할지를 정의합니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd            # ArgoCD가 설치된 namespace
spec:
  project: default             # 어느 AppProject에 속하는지

  # 소스: Git 어디에서 가져오나
  source:
    repoURL: https://github.com/my-org/my-repo
    targetRevision: main       # 브랜치, 태그, 커밋 SHA 모두 가능
    path: k8s/overlays/prod    # 레포 내 경로 (Kustomize, Helm 등)

  # 목적지: 어느 클러스터/네임스페이스에 배포하나
  destination:
    server: https://kubernetes.default.svc   # 현재 클러스터
    namespace: production

  # Sync 정책
  syncPolicy:
    automated:
      prune: true              # Git에서 삭제된 리소스 자동 제거
      selfHeal: true           # 수동으로 변경된 리소스 자동 복구
    syncOptions:
      - CreateNamespace=true   # namespace 없으면 자동 생성

source — Helm 차트 배포

Helm 차트를 사용할 경우 source에 helm 섹션을 추가합니다.

  source:
    repoURL: https://charts.bitnami.com/bitnami
    chart: redis               # 차트 이름
    targetRevision: 18.x.x     # 차트 버전
    helm:
      releaseName: my-redis
      values: |
        auth:
          enabled: false
        replica:
          replicaCount: 2

syncPolicy — Sync 동작 제어

옵션	설명	권장
`automated.prune`	Git에서 삭제된 리소스를 클러스터에서도 삭제	운영 환경 주의
`automated.selfHeal`	클러스터에서 수동 변경 시 Git 상태로 되돌림	GitOps 원칙상 권장
`CreateNamespace=true`	destination namespace가 없으면 자동 생성	권장
`ServerSideApply=true`	kubectl apply 대신 server-side apply 사용	CRD 충돌 방지 시 유용
`RespectIgnoreDifferences=true`	ignoreDifferences 설정을 Sync 시에도 적용	상황에 따라

Application 상태 이해하기

ArgoCD Web UI에서 보이는 상태는 Sync 상태와 Health 상태 두 가지 축으로 표시됩니다.

Sync 상태

Synced OutOfSync Unknown

Synced — Git desired state와 클러스터 실제 상태가 일치
OutOfSync — 차이가 있음. 아직 Sync 안 했거나 수동 변경이 있는 경우
Unknown — 상태를 알 수 없음 (클러스터 연결 문제 등)

Health 상태

Healthy Progressing Degraded Missing

Healthy — 모든 리소스가 정상 동작 중
Progressing — Deployment rollout 중 등 아직 완료되지 않은 상태
Degraded — 일부 리소스가 비정상 (Pod CrashLoopBackOff 등)
Missing — Git에는 있는데 클러스터에 리소스가 없음

AppProject — "누가 어디에 배포할 수 있나"

AppProject는 Application을 묶는 논리적 그룹입니다. 팀별 또는 환경별로 배포 가능한 Git 레포, 클러스터, 네임스페이스를 제한하는 RBAC 경계 역할을 합니다.

Application

"무엇을 어디에 배포할 것인가"를 정의하는 배포 단위. 반드시 하나의 AppProject에 속해야 합니다.

AppProject

Application들의 논리적 묶음. 허용된 Git 레포, 클러스터, 네임스페이스, 리소스 종류를 제한합니다.

apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-backend
  namespace: argocd
spec:
  description: "백엔드 팀 프로젝트"

  # 이 프로젝트의 Application이 사용할 수 있는 Git 레포
  sourceRepos:
    - https://github.com/my-org/backend-*   # 와일드카드 가능
    - https://charts.bitnami.com/bitnami

  # 배포 가능한 클러스터와 네임스페이스
  destinations:
    - server: https://kubernetes.default.svc
      namespace: backend-prod
    - server: https://kubernetes.default.svc
      namespace: backend-staging

  # 배포 허용 리소스 종류 (화이트리스트)
  clusterResourceWhitelist:
    - group: ""
      kind: Namespace          # Namespace 생성 허용
  namespaceResourceBlacklist:
    - group: ""
      kind: ResourceQuota      # ResourceQuota는 배포 금지

  # RBAC 역할 정의
  roles:
    - name: developer
      description: "배포 권한만 있는 개발자 역할"
      policies:
        - p, proj:team-backend:developer, applications, get, team-backend/*, allow
        - p, proj:team-backend:developer, applications, sync, team-backend/*, allow
      groups:
        - my-org:backend-team  # GitHub org 팀과 연동

default 프로젝트

ArgoCD 설치 시 default AppProject가 자동으로 생성됩니다. sourceRepos: ["*"], destinations: [서버: *, 네임스페이스: *]로 모든 것을 허용하기 때문에, 운영 환경에서는 반드시 팀별 AppProject를 별도로 만들고 default 프로젝트 사용을 제한하는 것을 권장합니다.

실무 구성 패턴

패턴 1 — 팀별 AppProject 분리

# 백엔드 팀 프로젝트
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-backend
spec:
  sourceRepos:
    - https://github.com/my-org/backend-*
  destinations:
    - server: https://kubernetes.default.svc
      namespace: "backend-*"    # backend- 로 시작하는 네임스페이스만 허용
---
# 프론트엔드 팀 프로젝트
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: team-frontend
spec:
  sourceRepos:
    - https://github.com/my-org/frontend-*
  destinations:
    - server: https://kubernetes.default.svc
      namespace: "frontend-*"

패턴 2 — 환경별 AppProject 분리

# 운영 환경 프로젝트 (수동 Sync만 허용)
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
  name: env-production
spec:
  sourceRepos:
    - https://github.com/my-org/*
  destinations:
    - server: https://prod-cluster.example.com
      namespace: "*"
  # 운영 환경: Auto-sync 비활성화를 정책으로 강제
  syncWindows:
    - kind: deny
      schedule: "* * * * *"    # 항상 자동 배포 차단
      duration: 1h
      applications: ["*"]
      manualSync: true         # 수동 Sync는 허용

패턴 3 — ignoreDifferences로 Sync 노이즈 줄이기

Deployment의 replicas처럼 HPA가 관리하는 필드는 ArgoCD가 OutOfSync로 감지합니다. ignoreDifferences로 제외할 수 있습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  ignoreDifferences:
    - group: apps
      kind: Deployment
      jsonPointers:
        - /spec/replicas        # HPA가 관리하는 replicas 무시
    - group: ""
      kind: Secret
      jsonPointers:
        - /data                 # 외부에서 주입된 Secret 데이터 무시

자주 하는 실수

prune: true를 운영 환경에 바로 적용하는 경우

prune: true는 Git에서 파일을 삭제하면 클러스터 리소스도 같이 삭제합니다. 처음에는 prune: false로 시작해서 ArgoCD가 어떤 리소스를 prune 대상으로 잡는지 확인한 뒤 활성화하세요.

모든 Application을 default 프로젝트에 넣는 경우

default 프로젝트는 모든 레포와 클러스터에 접근 가능합니다. 팀이 늘어나면 반드시 AppProject를 분리해서 격리하세요.

App of Apps 패턴

Application을 하나씩 수동으로 만들지 않고, 하나의 "루트 Application"이 다른 Application YAML들을 Git에서 읽어서 자동으로 생성하게 할 수 있습니다. 이를 App of Apps 패턴이라고 부릅니다. ArgoCD를 처음 부트스트랩할 때 유용합니다.

마치며

Application은 배포 단위, AppProject는 그 배포의 경계와 권한을 정의합니다. 작은 팀에서는 default 프로젝트 하나로 시작해도 되지만, 팀이 여러 개거나 운영/개발 환경을 명확히 분리해야 한다면 처음부터 AppProject 구조를 잡아두는 것을 권장합니다.

다음 편에서는 ApplicationSet을 사용해서 여러 클러스터에 배포를 자동화하는 방법을 다룹니다.

다음 편

3편 — ApplicationSet으로 멀티 클러스터 배포 자동화

ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리

BinaryNumber — Sat, 16 May 2026 16:21:08 +0900

GitOps / ArgoCD 시리즈

1편 — ArgoCD Helm 설치 시 생성되는 컴포넌트 역할 정리 (현재 글)
2편 — ArgoCD Application, AppProject 개념 정리
3편 — ApplicationSet으로 멀티 클러스터 배포 자동화
4편 — ArgoCD Notifications Slack 연동 가이드

Helm으로 ArgoCD를 설치하면 한 namespace 안에 여러 Deployment와 StatefulSet이 생깁니다. 처음 보면 뭐가 뭔지 헷갈리는데, 각 컴포넌트가 담당하는 역할이 명확히 나뉩니다. 이 글에서는 kubectl get pod -n argocd 했을 때 보이는 각 파드가 무슨 일을 하는지 정리합니다.

테스트 환경: ArgoCD v2.x, argo-cd Helm chart (argoproj/argo-cd)

설치 후 생성되는 파드 목록

$ kubectl get pod -n argocd

NAME                                                READY   STATUS
argocd-server-xxxxxxxxx-xxxxx                       1/1     Running   ← Deployment
argocd-repo-server-xxxxxxxxx-xxxxx                  1/1     Running   ← Deployment
argocd-application-controller-0                     1/1     Running   ← StatefulSet
argocd-applicationset-controller-xxxxxxxxx-xxxxx    1/1     Running   ← Deployment
argocd-notifications-controller-xxxxxxxxx-xxxxx     1/1     Running   ← Deployment
argocd-redis-xxxxxxxxx-xxxxx                        1/1     Running   ← Deployment
argocd-dex-server-xxxxxxxxx-xxxxx                   1/1     Running   ← Deployment (SSO 사용 시)

application-controller만 StatefulSet이고 나머지는 전부 Deployment입니다. StatefulSet인 이유는 클러스터 상태 캐시를 안정적으로 유지하고, HA 구성 시 샤딩을 위해 고정된 파드 식별자가 필요하기 때문입니다.

컴포넌트별 역할 상세

argocd-server

Deployment

ArgoCD의 API 게이트웨이이자 Web UI 서버입니다. 외부에서 들어오는 모든 요청이 여기를 통합니다.

gRPC / REST API 제공 — CLI(argocd)와 Web UI가 이 서버와 통신
RBAC 인증 처리 — 어떤 사용자가 어떤 Application에 접근할 수 있는지 판단
Dex와 연동해서 SSO 토큰 검증
Webhook 수신 — GitHub/GitLab Push 이벤트를 받아서 즉시 Sync 트리거

argocd-repo-server

Deployment

Git 레포지토리에서 매니페스트를 가져와 최종 YAML로 변환하는 컴포넌트입니다. ArgoCD에서 CPU를 가장 많이 쓰는 컴포넌트입니다.

Git clone / fetch 수행
Helm, Kustomize, Jsonnet, Plain YAML 렌더링 — helm template 실행이 여기서 일어남
렌더링 결과를 Redis에 캐시해서 동일 커밋 반복 렌더링 방지
커스텀 플러그인(CMP, Config Management Plugin) 실행도 여기서 처리

argocd-application-controller

StatefulSet

ArgoCD의 핵심 컴포넌트입니다. Git의 desired state와 실제 클러스터 상태를 지속적으로 비교하고, 차이가 있으면 Sync(배포)를 실행합니다.

주기적으로 클러스터 상태를 조회해서 Redis에 캐시
Repo Server에서 받은 매니페스트와 실제 상태 비교 → OutOfSync / Synced 판단
Auto-sync 설정 시 자동으로 kubectl apply 수행
Health 상태 평가 — Deployment rollout, PVC 바인딩 등 리소스별 상태 판단
HA 구성 시 샤딩으로 여러 클러스터를 분산 처리 (인스턴스 인덱스 기반)

argocd-applicationset-controller

Deployment

ApplicationSet 커스텀 리소스를 감시해서 Application을 자동으로 생성·업데이트·삭제합니다.

List, Cluster, Git, Matrix 등 다양한 generator로 Application 목록 생성
멀티 클러스터 배포 자동화 — 클러스터가 추가되면 Application 자동 생성
PR 환경 자동화 — PR 오픈 시 임시 환경 생성, 머지 시 삭제

argocd-notifications-controller

Deployment

Application 상태 변화를 감지해서 외부로 알림을 보내는 컴포넌트입니다.

Sync 성공 / 실패, Health 상태 변화 감지
Slack, 이메일, PagerDuty, Teams, Webhook 등 다양한 채널 지원
trigger + template 조합으로 유연한 알림 조건 정의 가능

argocd-redis

Deployment

API Server와 Application Controller가 클러스터 상태 캐시를 공유하는 저장소입니다.

클러스터 리소스 상태 캐시 — 매번 kube-apiserver를 호출하지 않도록
Repo Server 렌더링 결과 캐시
재시작하면 데이터가 초기화됨 (캐시 전용, 영구 저장 아님)
HA 구성 시 Redis Sentinel 또는 Redis Cluster로 대체 가능

argocd-dex-server

Deployment (선택)

OIDC 브로커 역할을 하는 SSO 컴포넌트입니다. GitHub, Google, LDAP, SAML 등 외부 IdP와 ArgoCD 사이에서 인증을 중계합니다.

외부 IdP로부터 받은 토큰을 ArgoCD가 이해할 수 있는 형태로 변환
SSO가 필요 없으면 dex.enabled: false로 비활성화 가능
비활성화 시 ArgoCD 로컬 사용자 또는 직접 OIDC 연동으로 대체

한눈에 정리

컴포넌트	종류	핵심 역할	리소스 특성
`argocd-server`	Deployment	API / Web UI / Webhook 수신	외부 트래픽 집중
`argocd-repo-server`	Deployment	Git clone + 매니페스트 렌더링	CPU 집중
`argocd-application-controller`	StatefulSet	상태 비교 + Sync 실행	메모리 집중, 핵심
`argocd-applicationset-controller`	Deployment	ApplicationSet → Application 생성	경량
`argocd-notifications-controller`	Deployment	상태 변화 감지 + 알림 발송	경량
`argocd-redis`	Deployment	상태 캐시 공유	메모리, 재시작 시 초기화
`argocd-dex-server`	Deployment	OIDC / SSO 인증 브로커	선택, SSO 불필요 시 비활성화

Git Push부터 배포까지 전체 흐름

[Git repo] ─ push ──────────────────────────────────────────▶ [argocd-server] (Webhook 수신) │ ▼ [argocd-repo-server] ◀── 매니페스트 렌더링 요청 ────────── [argocd-application-controller] │ │ │ Helm/Kustomize 실행 │ 상태 비교 ▼ │ (desired vs actual) [argocd-redis] ◀── 캐시 저장 ──────────────────────────────────────▶ [argocd-application-controller] │ │ kubectl apply ▼ [Kubernetes cluster] │ │ Sync 결과 ▼ [argocd-notifications-controller] ──▶ Slack

리소스 설정 예시

처음 설치할 때 최소한으로 잡아야 할 리소스 설정입니다. repo-server는 Helm 렌더링이 많을수록 CPU를 많이 쓰고, application-controller는 관리하는 Application/클러스터 수에 비례해서 메모리가 늘어납니다.

# values.yaml

server:
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "500m"
      memory: "256Mi"

repoServer:
  resources:
    requests:
      cpu: "200m"
      memory: "256Mi"
    limits:
      cpu: "1000m"      # Helm 렌더링 시 CPU 급증
      memory: "512Mi"

controller:
  resources:
    requests:
      cpu: "250m"
      memory: "512Mi"
    limits:
      cpu: "1000m"
      memory: "2Gi"     # Application 수에 비례해서 증가

redis:
  resources:
    requests:
      cpu: "100m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "128Mi"

applicationSet:
  resources:
    requests:
      cpu: "100m"
      memory: "128Mi"
    limits:
      cpu: "200m"
      memory: "256Mi"

notifications:
  resources:
    requests:
      cpu: "100m"
      memory: "64Mi"
    limits:
      cpu: "200m"
      memory: "128Mi"

# SSO 불필요 시 Dex 비활성화
dex:
  enabled: false

자주 하는 실수

repo-server CPU limit을 너무 낮게 잡는 경우

Helm 차트가 크거나 Application이 많으면 repo-server에서 동시에 여러 렌더링이 일어납니다. CPU limit이 너무 낮으면 Sync가 느려지거나 타임아웃이 발생합니다. 처음에는 넉넉하게 잡고 실제 사용량을 보면서 줄이세요.

application-controller 메모리 부족

관리하는 클러스터와 Application이 늘어날수록 application-controller의 메모리 사용량이 선형으로 증가합니다. OOMKilled가 반복되면 limit을 올리거나 HA 샤딩 구성을 검토하세요.

Webhook 설정으로 Sync 속도 개선

기본 설정에서 ArgoCD는 3분마다 Git을 polling합니다. GitHub/GitLab Webhook을 argocd-server에 연결하면 Push 즉시 Sync가 트리거되어 배포 지연이 없어집니다.

마치며

ArgoCD는 컴포넌트가 많아 보이지만, 역할을 나눠 보면 구조가 명확합니다. 문제가 생겼을 때 어느 파드 로그를 봐야 할지 파악하는 것만으로도 트러블슈팅 시간이 크게 줄어듭니다. Sync가 안 되면 application-controller, 렌더링 에러면 repo-server, 로그인 문제면 dex나 argocd-server를 먼저 확인하세요.

다음 편

2편 — ArgoCD Application, AppProject 개념 정리

Loki write / read / backend 역할 정리

BinaryNumber — Sat, 16 May 2026 16:10:14 +0900

Helm으로 Loki를 설치하면 loki-write, loki-backend StatefulSet과 loki-read Deployment가 생깁니다. 처음 보면 "왜 파드가 이렇게 많지?" 싶은데, 이건 Loki의 Simple Scalable 배포 모드 때문입니다.

이 글에서는 세 가지 배포 모드가 무엇인지, 그리고 각 StatefulSet이 내부적으로 어떤 컴포넌트를 묶어놓은 건지 정리합니다.

테스트 환경: Loki v3.x, loki-stack Helm chart

Loki의 3가지 배포 모드

Loki는 하나의 바이너리로 배포 모드를 target 파라미터로 제어합니다.

1. Monolithic (단일 모드)

모든 컴포넌트가 하나의 파드에서 실행됩니다. 개발 환경이나 소규모 로그 수집에 적합하지만 수평 확장이 안 됩니다.

deploymentMode: SingleBinary

loki:
  commonConfig:
    replication_factor: 1
  storage:
    type: filesystem

2. Simple Scalable (권장 모드) — Helm 기본값

역할을 write, read, backend 세 그룹으로 나눠서 배포합니다. 각 그룹을 독립적으로 스케일링할 수 있어서 운영 환경에 적합합니다.

deploymentMode: SimpleScalable

3. Microservices (완전 분산 모드)

모든 컴포넌트를 개별 Deployment로 분리합니다. 세밀한 리소스 제어가 가능하지만 관리 복잡도가 높아서 대규모 환경에서만 사용합니다.

deploymentMode: Distributed

Simple Scalable의 세 컴포넌트 그룹

Helm 설치 후 확인하면 이렇게 나타납니다. read는 Stateless라서 Deployment, write와 backend는 디스크 상태(WAL, 인덱스)가 필요해서 StatefulSet입니다.

$ kubectl get statefulset -n monitoring

NAME             READY   AGE
loki-backend     1/1     5m
loki-write       3/3     5m

$ kubectl get deployment -n monitoring

NAME             READY   AGE
loki-read        2/2     5m

write

로그 수집 입구. 받아서 버퍼링하고 저장.

Distributor Ingester

read

Grafana 쿼리 처리. 분할하고 병렬 조회.

Query Frontend Querier

backend

백그라운드 작업. 압축, 알림, 인덱스 캐시.

Compactor Ruler Index Gateway

write — 로그를 받아서 저장

[Promtail / Alloy] → [write: Distributor] → [write: Ingester] → [Object Storage]

Distributor

Promtail이 로그를 보내면 가장 먼저 만나는 컴포넌트입니다.

들어오는 로그의 라벨 유효성 검사
스트림 해시 기반으로 어느 Ingester로 보낼지 결정 (일관된 해시링)
ingestion_rate_limit 초과 시 429 응답 반환
자체 상태 없음 — stateless하게 동작

Ingester

Distributor에게 받은 로그를 메모리에 청크로 버퍼링했다가 Object Storage로 플러시합니다.

로그 스트림을 메모리 청크에 압축 저장
일정 조건(시간 또는 크기)이 되면 S3 등으로 플러시
WAL(Write-Ahead Log)을 디스크에 기록해서 파드 재시작 시 복구 가능
Stateful하기 때문에 StatefulSet으로 배포됨

# Helm values.yaml — write 스케일링
write:
  replicas: 3
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1000m"
      memory: "1Gi"

언제 늘리나: 로그 수집 지연이 발생하거나 Distributor에서 rate limit 에러가 많이 나면 write 레플리카를 늘립니다.

read — 쿼리를 받아서 조회

[Grafana] → [read: Query Frontend] → [read: Querier] → [Ingester] + [Object Storage]

Query Frontend

Grafana가 LogQL 쿼리를 보내면 가장 먼저 받는 컴포넌트입니다.

쿼리를 시간 단위로 잘게 분할해서 여러 Querier에게 병렬 처리 위임
결과를 캐시해서 동일 쿼리 반복 시 빠르게 반환 (memcached 연동 가능)
쿼리 우선순위 큐 관리

Querier

실제로 데이터를 가져오는 컴포넌트입니다.

Ingester와 Object Storage 양쪽에서 동시에 조회
- Ingester: 아직 플러시되지 않은 최신 로그 (수 분 이내)
- Object Storage: 플러시된 과거 로그
두 결과를 합쳐서 중복 제거 후 반환

# Helm values.yaml — read 스케일링
read:
  replicas: 2
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "2000m"
      memory: "2Gi"

언제 늘리나: Grafana에서 로그 조회가 느리거나 타임아웃이 발생하면 read 레플리카를 늘립니다.

backend — 백그라운드 작업

[backend: Compactor] → 인덱스 압축 + 오래된 로그 삭제 [backend: Ruler] → LogQL 알림 규칙 평가 → AlertManager [backend: Index Gateway] → Querier 인덱스 캐시 중계

Compactor

작은 인덱스 파일들을 하나로 압축해서 조회 성능 향상
retention_period 설정에 따라 오래된 로그 삭제
한 번에 하나만 실행 — 레플리카는 1개가 원칙

Ruler

LogQL 표현식으로 정의한 알림 규칙을 주기적으로 평가
조건 충족 시 AlertManager로 알림 전송
Prometheus Ruler와 동일한 개념

Index Gateway

Querier가 매번 Object Storage에서 인덱스를 읽는 대신 캐시된 인덱스 제공
대규모 환경에서 Object Storage 요청 수 감소 → 비용 절감

# Helm values.yaml — backend 설정
backend:
  replicas: 1  # 대부분 1개로 충분
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

한눈에 정리

StatefulSet	내부 컴포넌트	역할	스케일링 기준
`write` (StatefulSet)	Distributor, Ingester	로그 수집 + 버퍼링 + 저장	수집 지연 / rate limit 에러
`read` (Deployment)	Query Frontend, Querier	쿼리 처리 + 데이터 조회	조회 느림 / 타임아웃
`backend` (StatefulSet)	Compactor, Ruler, Index Gateway	압축 / 알림 / 인덱스 캐시	거의 건드릴 일 없음

자주 하는 실수

replication_factor를 1로 설정하고 write를 3개 띄우는 경우

replication_factor: 1이면 하나의 Ingester에만 저장되므로, 그 파드가 재시작될 때 미플러시 로그가 유실될 수 있습니다. write 레플리카 수와 replication_factor를 맞춰야 합니다.

loki:
  commonConfig:
    replication_factor: 3  # write replicas와 동일하게
write:
  replicas: 3

Object Storage 없이 SimpleScalable 모드를 쓰는 경우

Simple Scalable 모드는 반드시 외부 Object Storage가 필요합니다. filesystem 스토리지는 Monolithic 모드에서만 동작합니다. 로컬 환경에서 테스트하려면 MinIO를 함께 띄우세요.

실무 설정 예시

# custom-values.yaml

deploymentMode: SimpleScalable

loki:
  storage:
    type: s3
    s3:
      region: ap-northeast-2
      bucketnames: my-loki-chunks
  commonConfig:
    replication_factor: 3

write:
  replicas: 3
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "1"
      memory: "1Gi"

read:
  replicas: 2
  resources:
    requests:
      cpu: "500m"
      memory: "512Mi"
    limits:
      cpu: "2"
      memory: "2Gi"

backend:
  replicas: 1
  resources:
    requests:
      cpu: "100m"
      memory: "256Mi"
    limits:
      cpu: "500m"
      memory: "512Mi"

마치며

Loki의 Simple Scalable 모드는 쓰기/읽기 부하를 독립적으로 조절할 수 있어서 운영 환경에서 효율적입니다. 실제로 로그 수집량이 많아지면 write만 늘리고, Grafana 조회가 느려지면 read만 늘리면 되기 때문에 리소스 낭비가 없습니다.

1주차 스터디 실습 정리

BinaryNumber — Wed, 18 Mar 2026 21:14:53 +0900

서종호(가시다)님의 AEWS 4기 스터디 내용을 기반으로 참고하여 학습 목적으로 작성하였습니다.

1주차) EKS Cluster Endpoint Access 소개

Mac 로컬 환경 세팅 (awscli, k8s tools, teraform)

# Install aws cli
brew install awscli
aws --version

# iam (주체) 자격 증명 설정
aws configure
AWS Access Key ID : <액세스 키 입력>
AWS Secret Access Key : <시크릿 키 입력>
Default region name : ap-northeast-2

# 확인
aws sts get-caller-identity

# 기본 Key Pair 생성 (pem 파일 생성)
aws ec2 create-key-pair \
  --key-name my-keypair \
  --query 'KeyMaterial' \
  --output text > my-keypair.pem

# 권한 설정
chmod 400 my-keypair.pem

# 확인
aws ec2 describe-key-pairs --key-names my-keypair

# Install kubectl
brew install kubernetes-cli
kubectl version --client=true

# Install krew
brew install krew

# Install k9s
brew install k9s

# Install kube-ps1
brew install kube-ps1

# Install kubectx
brew install kubectx


# kubectl 출력 시 하이라이트 처리
brew install kubecolor
echo "alias k=kubectl" >> ~/.zshrc
echo "alias kubectl=kubecolor" >> ~/.zshrc
echo "compdef kubecolor=kubectl" >> ~/.zshrc

# k8s krew path : ~/.zshrc 아래 추가
export PATH="${KREW_ROOT:-$HOME/.krew}/bin:$PATH"

# Install Helm
brew install helm
helm version

# tfenv 설치
brew install tfenv

# 설치 가능 버전 리스트 확인
tfenv list-remote

# 테라폼 특정 버전 설치
tfenv install 1.14.6

# 테라폼 특정 버전 사용 설정 
tfenv use 1.14.6

# tfenv로 설치한 버전 확인
tfenv list

# 테라폼 버전 정보 확인
terraform version

# 자동완성
terraform -install-autocomplete

## 참고 .zshrc 에 아래 추가됨
cat ~/.zshrc
autoload -U +X bashcompinit && bashcompinit
complete -o nospace -C /usr/local/bin/terraform terraform

EKS Public Endpoint Cluster 실습

# 코드 다운로드
git clone https://github.com/gasida/aews.git
cd aews
tree aews

# 작업 디렉터리 이동
cd 1w

# 변수 지정
aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text
export TF_VAR_KeyName=$(aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text)
export TF_VAR_ssh_access_cidr=$(curl -s ipinfo.io/ip)/32
echo $TF_VAR_KeyName $TF_VAR_ssh_access_cidr

# 배포 : 12분 정도 소요
terraform init
terraform plan
nohup sh -c "terraform apply -auto-approve" > create.log 2>&1 &
tail -f create.log


# 자격증명 설정
aws eks update-kubeconfig --region ap-northeast-2 --name myeks

# k8s config 확인 및 rename context
cat ~/.kube/config
cat ~/.kube/config | grep current-context | awk '{print $2}'
kubectl config rename-context $(cat ~/.kube/config | grep current-context | awk '{print $2}') myeks
cat ~/.kube/config | grep current-context

EKS Public&Private Endpoint Cluster 실습

# 코드수정
#  endpoint_public_access = true
#  endpoint_private_access = true
#  endpoint_public_access_cidrs = [
#    var.ssh_access_cidr
#  ]
terraform apply -auto-approve

EKS Fully Private Cluster 실습

#EKS Fully Private Cluster 배포
# 실습 디렉터리 진입
cd eks-private

# 변수 지정
aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text
export TF_VAR_KeyName=$(aws ec2 describe-key-pairs --query "KeyPairs[].KeyName" --output text)
export TF_VAR_ssh_access_cidr=$(curl -s ipinfo.io/ip)/32
echo $TF_VAR_KeyName $TF_VAR_ssh_access_cidr

# 초기화
terraform init
terraform plan

# vpc 배포 : 2분 소요 -> 이후 aws vpc 정보 확인!
terraform apply -target="module.vpc" -auto-approve

#bastion EC2 접속 후 확인
# bastion ec2 접속
ssh -o StrictHostKeyChecking=no ubuntu@$(terraform output -raw bastion_ec2-public_ip)

# admin IAM User 자격 증명 설정
aws configure

# 자격증명 설정
aws eks --region ap-northeast-2 update-kubeconfig --name eks-private
kubectl config rename-context $(cat ~/.kube/config | grep current-context | awk '{print $2}') eks-private

# eks access endpoint 확인
APIDNS=$(aws eks describe-cluster --name eks-private | jq -r .cluster.endpoint | cut -d '/' -f 3)
echo $APIDNS
4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com

dig +short $APIDNS
10.0.14.147
10.0.28.171

# kubectl 조회 시도 : DNS Lookup resolved" host="4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com" address=[{"IP":"10.0.28.171","Zone":""},{"IP":"10.0.14.147","Zone":""}]
kubectl cluster-info
kubectl get node -v=9
...
	curl -v -XGET  -H "Accept: application/json;as=Table;v=v1;g=meta.k8s.io,application/json;as=Table;v=v1beta1;g=meta.k8s.io,application/json" -H "User-Agent: kubectl/v1.34.2 (linux/amd64) kubernetes/0ea4984" 'https://4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com/api/v1/nodes?limit=500'
 >
I0312 18:36:06.092396    2708 round_trippers.go:547] "HTTP Trace: DNS Lookup resolved" host="4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com" address=[{"IP":"10.0.28.171","Zone":""},{"IP":"10.0.14.147","Zone":""}]

# eks 등 배포 : 14분 소요
terraform apply -auto-approve

# 자격증명 설정
aws eks --region ap-northeast-2 update-kubeconfig --name eks-private
kubectl config rename-context $(cat ~/.kube/config | grep current-context | awk '{print $2}') eks-private

# kubectl 조회 시도
kubectl get node -v=7
...
I0312 18:01:51.102015   28018 round_trippers.go:527] "Request" verb="GET" url="https://4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com/api?timeout=32s" headers=<
        Accept: application/json;g=apidiscovery.k8s.io;v=v2;as=APIGroupDiscoveryList,application/json;g=apidiscovery.k8s.io;v=v2beta1;as=APIGroupDiscoveryList,application/json
        User-Agent: kubectl/v1.35.2 (darwin/arm64) kubernetes/fdc9d74
 E0312 18:02:21.493542   28018 memcache.go:265] "Unhandled Error" err="couldn't get current server API group list: Get \"https://4924E16AD07400AA0CA66718E179E887.gr7.ap-northeast-2.eks.amazonaws.com/api?timeout=32s\": dial tcp 10.0.14.147:443: i/o timeout"

# 자격증명 삭제
rm -rf ~/.kube/config

결과화면

[VPC]

[EKS]

[Public Endpoint]

[Public & Private Endpoint]

[Private Endpoint]

후기

실무에 도움이 되는 도구 - 사람 친화적인 설정

기능	효과
k9s	GUI처럼 관리
kubectx/kubens	빠른 환경 전환
kube-ps1	사고 방지
kubecolor	가독성
alias	속도
krew	확장성

새로 알게된 내용

ENI owned ENI 확인 - 소유주와 인스턴스 소유주가 다른 것 확인