L.O.K

[Azure] Application Gateway 환경에서 Graceful Pod Termination 구현하기

록흐 — Sat, 6 Jun 2026 12:04:33 +0900

Graceful하게 Pod 종료하기

graceful하게 pod를 종료하려면 큰 틀에서 두 가지 조건을 만족해야 한다. 1) 신규 트래픽이 종료 중인 파드로 전달되면 안된다. 2) 이미 들어온 트래픽이 처리가 될 때까지 파드는 종료되면 안된다.

lordofkangs.tistory.com

이전 포스팅에서 K8s 환경에서 Graceful하게 pod 종료하는 방법을 다루어 보았다.

요약하면

graceful하게 pod를 종료하려면 큰 틀에서 두 가지 조건을 만족해야 하는데,

1) 신규 트래픽이 종료 중인 파드로 전달되면 안된다.

2) 이미 들어온 트래픽이 처리가 될 때까지 파드는 종료되면 안된다.

신규 트래픽은 endpoint로 막히게 되고

기존 트래픽은 Linux의 conntrack 모듈로 인해 [ ClientIP - PodIP ] TCP세션으로 유지되므로, 클라이언트와의 세션이 안전하게 종료될때까지 파드만 정상상태를 유지하면 된다는 것이다.

그래서 파드에 두 가지 설정이 필요했다.

1) 파드에 preStop 설정 추가

2) 파드에 terminationGracePeriodSeconds 설정 추가

여기서 만약 Azure 환경의 Application Gateway를 사용한다면 Graceful한 파드 종료를 위해서 Ingress에 한 가지 설정을 더 추가해야 한다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
  namespace: test
  annotations:
    kubernetes.io/ingress.class: azure-application-gateway
    # Connection Draining 활성화
    appgw.ingress.kubernetes.io/connection-draining: "true"
    # 기존 연결을 최대 90초간 유지
    appgw.ingress.kubernetes.io/connection-draining-timeout: "90"

해당 어노테이션 설정이 필요한 이유는 Azure 환경의 Application Gateway이 동작하는 독특한 과정 때문이다.

Azure 환경의 Application Gateway는 일반적인 K8s LB가 아니라 Azure에서 커스텀하게 만든 서비스이다.

AKS는 AGIC라는 파드가 떠있는데, 이는 ingress 생성을 감지하여 ingress-> 서비스 -> endpoint -> 파드로의 정보를 수집하고 이를 토대로 Azure 환경에 Listener, Rule, BackendPool, BackendSetting을 생성하는 API를 호출한다. 이렇게 생성된 것들이 모여 트래픽을 파드로 라우팅하는 것이 Azure Application Gateway이다.

일반적인 K8S는 Client 와 파드 사이에 세션이 형성된다.

Azure에서는 Application Gateway가 Client와 Pod 사이의 Proxy 역할을 한다.

Client -> Application Gateway -> Pod

이것이 가능한 이유는 Application Gateway Subnet과 AKS Subet이 동일한 vnet에 있기에 가능하다.

# application-gateway subnet 정보
az network application-gateway show \
  -g <AG_RG>  \
  -n <AG_NAME> \
  --query "gatewayIPConfigurations[].subnet.id" \
  -o tsv


# aks subnet 정보
az aks show \
  -g <AKS_RG> \
  -n <AKS_NAME> \
  --query "agentPoolProfiles[0].vnetSubnetId" \
  -o tsv

위 커맨드로 subnet 정보를 조회하면 동일한 vnet에 있음을 확인할 수 있다.

그럼 여기서 graceful하게 pod를 종료하기 위한 두 가지 조건에 하나가 더 추가됨을 알 수 있다.

1) 신규 트래픽이 종료 중인 파드로 전달되면 안된다.

2) 이미 들어온 트래픽이 처리가 될 때까지 파드는 종료되면 안된다.

3) ApplicationGateway와 Pod 사이의 연결이 끊기면 안된다.

파드가 종료명령을 받으면 AGIC는 azure api를 호출하여 ApplicationGateway의 BackendPool 데이터에서 삭제된 Pod IP를 제거하여 더이상 client의 신규 요청이 종료된 pod로 보내지 않도록 해야한다. 이때 1번 조건을 만족하기 위해 제거된다.

문제는 2번 조건 만족을 위해 ApplicationGateway와 종료 요청 받은 Pod 사이의 세션을 유지해야 하는데, 별다른 설정이 없다면ApplicationGateway는 파드와의 세션 유지를 보장하지 않는다는 것이다. 그렇다면 파드에 preStop, terminationGracePeriodSeconds 설정을 하더라도 ApplicationGateway이 파드 사이와의 세션을 끊기에 세션은 유지가 되지 않고 Client는 영문 모를 502 에러를 마주하게 된다.

그러므로 preStop, terminationGracePeriodSeconds 과 더불어

아래 설정도 ingress에 추가하여 세션유지를 보장해야 graceful한 파드 종료를 보장할 수 있다.

    appgw.ingress.kubernetes.io/connection-draining: "true"
    appgw.ingress.kubernetes.io/connection-draining-timeout: "90"

Graceful하게 Pod 종료하기

록흐 — Fri, 5 Jun 2026 20:40:31 +0900

graceful하게 pod를 종료하려면 큰 틀에서 두 가지 조건을 만족해야 한다.

1) 신규 트래픽이 종료 중인 파드로 전달되면 안된다.

2) 이미 들어온 트래픽이 처리가 될 때까지 파드는 종료되면 안된다.

신규 트래픽이 종료 중인 파드로 전달되면 안된다.

신규 트래픽이 노드로 들어오면 kube-proxy가 iptables로 기록해둔 경로를 따라 service에서 endpoint 중 하나로 로드밸런싱한다. ( 원리 : https://lordofkangs.tistory.com/709 ) 이때 endpoint는 service에게 3가지 상태를 공유한다.

- ready : 트래픽을 받을 준비가 되었는가?

- serving : 요청 처리가 가능한가?

- terminating : 파드가 삭제중인가?

# 세 가지 플래그 확인하는 방법
kubectl get endpointslices -o json -l kubernetes.io/service-name=[서비스명]

파드가 종료되면 endpoint의 ready는 true에서 false로 변경되고 service는 ready가 false인 endpoint로 트래픽을 전달하지 않아 종료중인 파드에게 트래픽을 전달하지 않는다.

이미 들어온 트래픽이 처리가 될 때까지 파드는 종료되면 안된다.

신규 트래픽이 노드로 들어오면 kube-proxy가 iptables로 기록해둔 경로를 따라 파드로 전달하여 세션이 생성되지만 세션의 상태는 Linux의 conntrack 모듈로 관리된다. 한마디로 [ ClientIP - PodIP ]로 TCP 연결 상태를 추적 관리하므로, 파드가 종료 명령을 받아 endpoint의 ready 플래그가 false여도 파드 상태만 정상 상태로 지연시킬 수 있다면 종료 명령 받기전 생성된 세션은 트래픽이 처리될 때까지 유지할 수 있다는 것이다.

이를 증명하기 위해 한 가지 테스트를 해보자.

Nginx Deployment 메니페스트

1) preStop 설정 추가

2) terminationGracePeriodSeconds 설정 추가

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      terminationGracePeriodSeconds: 300
      containers:
      - name: nginx
        image: nginx:latest
        lifecycle:
          preStop:
            exec:
              command:
              - /bin/sh
              - -c
              - |
                echo "[$(date)] preStop start"
                sleep 240
                echo "[$(date)] preStop end"
        ports:
        - containerPort: 80

Nginx Service 메니페스트

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

Client 파드 메니페스트

apiVersion: v1
kind: Pod
metadata:
  name: curl-client
  namespace: test
spec:
  restartPolicy: Never
  containers:
  - name: curl
    image: curlimages/curl:8.8.0
    command:
    - /bin/sh
    - -c
    - |
      echo "curl client ready"
      sleep infinity

Client가 nginx 파드에 있는 파일을 다운로드 하여 TCP 세션을 유지하는 상황을 가정해보자.

우선 nginx 파드 내부로 exec하여 파일 하나를 설치한다.

dd if=/dev/zero of=/usr/share/nginx/html/1g.bin bs=1M count=1024

그리고 client 파드 내부로 exec하여 curl 명령어로 해당 파일을 다운로드 하여 세션을 유지한다.

curl http://nginx-service.test/1g.bin --limit-rate 100k -o /dev/null

아래 명령어로 client 파드와 nginx 파드의 ip와 nginx 파드가 떠있는 노드를 확인한다.

kubectl get pods -n test -o wide

nginx 파드가 떠있는 node 내부로 접속하여 아래 명령어를 실행한다.

# 10.233.111.16 : nginx 파드 ip
conntrack -L -p tcp | grep 10.233.111.16

출력 결과

src=10.233.111.16 : nginx 파드

dst=10.233.111.56 : client 파드

tcp      6 299 ESTABLISHED src=10.233.111.56 dst=10.233.16.192 sport=36916 dport=80 packets=911 bytes=47539 src=10.233.111.16 dst=10.233.111.56 sport=80 dport=36916 packets=5236 bytes=16801505 [ASSURED] mark=0 use=1

최초에 10.233.111.56(Client Pod)에서 10.233.16.192(NGINX Service)으로 요청이 유입된다. kube-proxy의 iptables 규칙에 의해 Service IP는 10.233.111.16(NGINX Pod)으로 DNAT된다. 이후 Client Pod(10.233.111.56)와 NGINX Pod(10.233.111.16) 사이의 TCP 연결이 ESTABLISHED 상태로 생성되며 해당 연결 정보는 Linux conntrack 테이블에 기록되어 관리된다.

여기서 파드가 종료명령을 받으면 어떻게 될까?

kubectl get endpointslices -o json -l kubernetes.io/service-name=nginx-service

                    "conditions": {
                        "ready": false,
                        "serving": true,
                        "terminating": true
                    },

endpoint는 ready가 false로 변경되며 신규 트래픽 유입이 막힌다.

파드는 preStop 설정에 의해 종료명령을 받더라도 프로세스 종료작업을 진행하지 않는다.

# 10.233.111.16 : nginx 파드 ip
conntrack -L -p tcp | grep 10.233.111.16

출력결과

tcp      6 299 ESTABLISHED src=10.233.111.56 dst=10.233.16.192 sport=36916 dport=80 packets=2731 bytes=142179 src=10.233.111.16 dst=10.233.111.56 sport=80 dport=36916 packets=15669 bytes=47039597 [ASSURED] mark=0 use=1

conntrack으로 확인해보면 파드가 종료명령을 받았는데도 아직 TCP 세션은 ESTABLISHED 상태로 유지됨을 확인할 수 있다. TCP 세션은 client 와 파드 사이의 연결로, 파드만 유지된다면 세션은 끊기지 않기 때문이다.

그러므로 파드를 안전하게 종료하려면

파드에 신규 트래픽 유입을 막고

파드의 모든 세션이 자발적으로 종료될때까지 종료를 지연시키는 것이 중요하다.

1) 파드에 preStop 설정 추가

2) 파드에 terminationGracePeriodSeconds 설정 추가

pod가 종료 명령을 받으면 내부적으로 SIGTERM 명령을 받아 안전하게 프로세스를 종료하는 작업을 진행한다.

preStop은 SIGTERM 명령이 들어오는 시간을 지연시켜준다. 요청이 들어오면 프로세스가 살아 있어야 하기에, 종료시키지 않고 유지시켜주는 작업이다. preStop으로 설정된 시간이 지나가면 SIGTERM 명령이 들어온다. 그러면 프로세스 정리작업이 시작된다. 프로세스가 정리되는데 시간이 오래 걸리고 서비스가 Stateful해서 프로세스가 안전하게 정리되어야 한다면 terminationGracePeriodSeconds 시간을 길게 잡아야 한다.

terminationGracePeriodSeconds 가 120초이고 preStop 60초이면 pod 종료 명령이 들어오고 60초 동안은 SIGTERM이 내부에서실행되지 않는다. 60초가 지나면 SIGTERM명령이 실행되고 프로세스 종료작업이 진행된다. 그리고 60초가 흐르면 파드는 종료된다.

참고자료

https://kubernetes.io/docs/tutorials/services/pods-and-endpoint-termination-flow/

PostgreSQL DB와 PGBouncer ( + Prepared Statements )

록흐 — Thu, 14 May 2026 20:38:30 +0900

Client가 PostgreSQL DB에서 Query를 실행한다는 것은 다음과 같다.

1) ClientA가 PostgreSQL DB auth에 성공한다. ( 세션 생성 )

2) PostgreSQL DB 내부에 ClientA 전용 process가 생성된다. ( backend process ) ( idle )

3) ClientA가 ClientA 전용 process 공간에서 BEGIN 으로 트랜잭션을 시작한다. ( idle in transaction )

4) ClientA가 쿼리를 실행한다. ( active )

5) ClientA가 COMMIT/ROLLBACK 으로 트랜잭션을 종료한다.

6) ClientA의 backend process/session은 유지되며 다음 요청을 기다린다. ( idle )

7) ClientA connection 이 종료되면 ClientA 전용 process 공간도 제거된다. ( 세션 종료 )

여기서 가장 큰 문제는 Client와 Process가 1 대 1로 매핑되므로 Client가 10개, 50개, 80개, 100개 이상으로 증가하게 되면, DB는 많은 프로세스를 관리함과 동시에 잦은 컨텍스트 스위칭에 시달려 성능 저하를 겪게 되는 것이다.

그렇다면

PGBouncer는 이 문제를 어떻게 해결할까?

PGBouncer가 PostgresSQL DB에 미리 고정된 범위의 backend process 생성해놓는다. ( pool 단위 )

PGBouncer는 PostgresSQL DB 대신 Client와 연결되어, Client를 번갈아 미리 생성해놓은 Backend Process에 할당하여 트랜잭션을 처리한다. Client가 100 개인데, backend process 가 10개라면 90개는 세션 연결 에러를 일으키지 않고 큐에서 차례를 기다리면 얌전히 대기한다. Client입장에서는 PGBouncer와 정상적으로 연결이 된 상태이기에 연결오류라고 인식하지 않는 것이다.

PGBouncer를 트랜잭션 모드로 동작시키면, 세션 단위가 아닌 트랜잭션 처리 단위 ( BEGIN - COMMIT/ROLLBACK )로 Backend Process를 할당한다. PGBouncer가 없다면 한 개의 세션에 한 개의 backend process 이지만, PGBouncer를 통한 다면 한 개의 세션동안 처리되는 다수의 트랜잭션 마다 backend process 여러 곳에 할당이 될 수 있는 것이다.

결과적으로

Client 개수가 아무리 많아져도 backend process는 고정된 범위 안의 개수로 유지가 되고 backend process가 종료되지도 않기 때문에 반복적인 컨텍스트 스위칭도 발생하지 않아 DB 리소스 부담이 덜해지는 것이다.

Prepared Statements

PGBouncer에도 한 가지 단점이 있었다. Client는 Prepared Statement를 사용하여 반복적인 쿼리 파싱 및 실행 계획 생성을 방지할 수 있다. 하지만 PGBouncer를 쓰게 되면 문제가 생기는게, Prepared Statement는 backend process 내부에 저장되지만 트랜잭션 마다 backend process가 변경되니, Client가 다음 트랜잭션에서 Prepared Statement를 이용할 수가 없어 비활성화 해야만한다. 그 결과 Client는 쿼리의 컬럼 타입 조회와 같은 메타데이터 조회 쿼리를 반복적으로 수행하게 되고, 이는 실제 비즈니스 쿼리 외의 추가적인 DB 부하로 이어진다.

개인적으로도 PGBouncer 오래된 버전을 쓰고 있어 Prepared Statement 기능을 사용하지 못하니 asyncpg가 typeinfo_tree 쿼리를 비정상적으로 많이 호출하여 DB CPU 부하가 100% 까지 반복적으로 Spike를 쳤다.

다행이도

PGBouncer는 1.21 버번 이후부터 Prepared Statement 기능을 사용할 수 있게 되었다.

https://www.postgresql.org/about/news/pgbouncer-1210-released-now-with-prepared-statements-2735/

PgBouncer는 Prepared Statement 사용 정보를 추적하고 있다가, backend process가 변경되더라도 해당 backend에 Prepared Statement를 다시 준비(re-prepare)하여 Prepared Statement를 지속적으로 재사용할 수 있도록 한다. asyncpg(Client)와 PgBouncer가 Prepared Statement를 사용할 수 있도록 활성화를 하자 놀랍도록 DB CPU 부하는 감소하였다.

이처럼

PGBouncer는 PostgresSQL DB가 안정적으로 프로세스를 관리할 수 있도록 함과 동시에 Prepared Statement 기능까지 갖추어진 효율적인 최적화 도구라 할 수 있다.

K8s readonly kubeconfig 파일 생성하기

록흐 — Thu, 14 May 2026 17:48:41 +0900

default 네임스페이스에 K8s Cluster 전역 조회 권한이 있는 ServiceAccount 생성 ( Secret 리소스 읽기 제외 )

apiVersion: v1
kind: ServiceAccount
metadata:
  name: read-only-no-secrets
  namespace: default
---
# Kubernetes RBAC는 명시적 허용만 가능(제외 불가)하므로
# core API group에서 secrets를 의도적으로 제외하고 나머지 리소스만 나열한다.
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: read-only-no-secrets
rules:
  - apiGroups: [""]
    resources:
      - pods
      - pods/log
      - pods/status
      - services
      - endpoints
      - configmaps
      - persistentvolumeclaims
      - persistentvolumes
      - namespaces
      - nodes
      - events
      - replicationcontrollers
      - resourcequotas
      - limitranges
      - serviceaccounts
      - bindings
      - componentstatuses
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apps"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["batch"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["networking.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["rbac.authorization.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["autoscaling"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["policy"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["discovery.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["apiextensions.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["scheduling.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["coordination.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["events.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["admissionregistration.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["certificates.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["node.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["flowcontrol.apiserver.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-only-no-secrets
subjects:
  - kind: ServiceAccount
    name: read-only-no-secrets
    namespace: default
roleRef:
  kind: ClusterRole
  name: read-only-no-secrets
  apiGroup: rbac.authorization.k8s.io

생성한 SA의 장기(만료 없음) 토큰 Secret 생성하기

apiVersion: v1
kind: Secret
metadata:
  name: read-only-no-secrets-token
  namespace: default
  annotations:
    kubernetes.io/service-account.name: read-only-no-secrets
type: kubernetes.io/service-account-token

kubeconfig 파일 생성하기

#!/usr/bin/env bash
set -euo pipefail

NAMESPACE="${NAMESPACE:-default}"
SECRET_NAME="${SECRET_NAME:-read-only-no-secrets-token}"
SA_NAME="${SA_NAME:-read-only-no-secrets}"
KUBECONFIG_OUT="${KUBECONFIG_OUT:-./readonly-kubeconfig.yaml}"

# 토큰 컨트롤러가 비동기로 채우므로 최대 ~10초 대기
TOKEN_B64=""
for i in 1 2 3 4 5; do
  TOKEN_B64=$(kubectl get secret "$SECRET_NAME" -n "$NAMESPACE" \
    -o jsonpath='{.data.token}' 2>/dev/null || true)
  if [ -n "$TOKEN_B64" ]; then break; fi
  echo "토큰이 아직 채워지지 않음 ($i/5), 2초 대기..." >&2
  sleep 2
done

if [ -z "$TOKEN_B64" ]; then
  echo "ERROR: $NAMESPACE/$SECRET_NAME 에 토큰이 없습니다." >&2
  echo "  - Secret이 존재하는지: kubectl get secret $SECRET_NAME -n $NAMESPACE" >&2
  echo "  - 어노테이션이 SA를 가리키는지 확인하세요." >&2
  exit 1
fi

TOKEN=$(printf '%s' "$TOKEN_B64" | base64 -d)
CA=$(kubectl get secret "$SECRET_NAME" -n "$NAMESPACE" -o jsonpath='{.data.ca\.crt}')

SERVER=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.server}')
CLUSTER=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].name}')

if [ -z "$CA" ] || [ -z "$SERVER" ] || [ -z "$CLUSTER" ]; then
  echo "ERROR: CA / server / cluster 중 일부를 가져오지 못했습니다." >&2
  echo "  CA len=${#CA} SERVER=$SERVER CLUSTER=$CLUSTER" >&2
  exit 1
fi

umask 077
cat > "$KUBECONFIG_OUT" <<EOF
apiVersion: v1
kind: Config
clusters:
- name: ${CLUSTER}
  cluster:
    server: ${SERVER}
    certificate-authority-data: ${CA}
users:
- name: ${SA_NAME}
  user:
    token: ${TOKEN}
contexts:
- name: read-only
  context:
    cluster: ${CLUSTER}
    user: ${SA_NAME}
    namespace: ${NAMESPACE}
current-context: read-only
EOF
chmod 600 "$KUBECONFIG_OUT"

echo "✓ kubeconfig 생성: $KUBECONFIG_OUT"
echo ""
echo "테스트:"
echo "  KUBECONFIG=$KUBECONFIG_OUT kubectl get pods -A      # OK"
echo "  KUBECONFIG=$KUBECONFIG_OUT kubectl get secrets      # Forbidden 정상"

Claude와 함께하는 개발환경 구축하기

록흐 — Fri, 1 May 2026 09:41:08 +0900

CICD 구축

Claude Agent들은 feauture 단위로 컨텍스트를 소비할거라, feature 개발이 끝나면 MR을 생성해 기능테스트를 하기로 계획했다.

Dev

MR이 생성되면 ArgoEvents로 구성된 CICD 파이프라인이 동작하면서 이미지를 빌드 및 푸시하고 HelmRepo의 dev-values.yaml의 이미지 태그를 변경한다. Dev K8s는 변경사항을 감지하고 Sync를 맞추어 배포를 진행하고 테스트를 진행한다.

Prod

테스트가 완료되면 Merge 이벤트를 발생시켜 CICD 파이프라인을 동작시키고 HelmRepo의 prod-values.yaml의 이미지 태그를 변경한다. Prod K8s는 변경사항을 감지하고 Sync를 맞추어 배포를 진행하고 테스트를 진행한다.

App of Apps

CICD App들은 app of apps 패턴으로 생성하여, Argocd Application CRD도 형상관리가 가능하게 하면서 migration에 용이하도록 하였다. 한가지 주의할 점은 Auto Sync를 막아놓고 eventbus -> eventsource, eventsensor 순으로 sync를 맞추고 제거시에는 eventsource,eventsensor -> eventbus 순으로 제거해야 한다. 동시에 sync를 맞추고 제거하면 eventbus가 hang에 걸려 제대로 삭제 되지 않는다.

Claude 설계

Plan

Main Claude에게 구현할 서비스 아키텍처를 주고 Planning을 시켜 계획을 세우면 Gemini로 한번 더 계획을 리뷰하도록 하였다. 이 과정은 Skill로 구현하고 리뷰가 완료되면 Todo 리스트를 작성시켜 단계적으로 개발에 들어갈 수 있도록 하였다. Todo 리스트는 크게 Feature 단위와 SubTask 단위로 나누고 SubTask 작업이 끝나면 Git Push를, Feature가 끝나면 Git MR을 생성하도록 하였다.

문법검사

Bash 툴을 써서 git push 커맨드가 동작하면 PreToolUse Hook을 동작시켜 문법검사 쉘스크립트를 동작시켰다. 만약 문법에 문제가 있다면 git push는 중단되고 문법검사 내용을 Lint-Runner Agent에게 던져서 원인 분석을 시킨 뒤, 원인 분석이 끝나면 그 결과를 개발 담당 Agent에게 던져서 코드를 수정하도록 구현하였다.

오류분석

기능 테스트 중 오류가 발생하면 Grafana MCP로 메트릭과 로그를, Kuberenetes MCP로 k8s 상태 정보를 조회하여 오류 데이터를 Error Manager Agent에게 던져서 원인 및 조치 방법을 분석하고 분석 결과가 나오면 그 결과를 개발 담당 Agent에게 던져서 코드를 수정하도록 구현하였다.

문서기록

개발 담당 Agent들이 Write,Edit 툴을 수행할 때마다 PostToolUse Hook을 걸어 그 기록을 docs 디렉토리의 activity.log로 기록하고 docs keeper Agent가 update-docs skill로 트리거되어 activity.log를 기준으로 git 명령어를 변경사항을 조회해, 사람이 이해할 수 있는 문서로 CHAGNELOG.md(무엇을 변경했는지)와 DESIONS.md(무엇을 결정했는지)를 기록하도록 하도록 하였다.

k8s Secret을 Git으로 관리하는 방법

록흐 — Thu, 30 Apr 2026 18:42:09 +0900

k8s Secret 은 Base64형식으로 민감한 정보가 그대로 노출되어 있어 git에 올려 관리할 수 없지만 한 가지 방법이 있다. Secret을 SealedSecret이라는 CRD로 암호화하여 Git에 올리고 SealedSecret가 배포되면 sealed-secrets 서비스가 SealedSecret 생성을 감지하고 복호화하여 Secret을 생성하여, Secret을 Git으로 관리할 수 있다.

sealed-secrets 서비스 K8S 환경에 배포하기

helm repo add bitnami https://charts.bitnami.com/bitnami 

helm upgrade --install sealed-secrets bitnami/sealed-secrets --namespace sealed-secrets --create-namespace

로컬에 kubeseal 설치하기

MacOS

brew install kubeseal

Linux

VERSION=0.36.6

wget https://github.com/bitnami-labs/sealed-secrets/releases/download/v${VERSION}/kubeseal-${VERSION}-linux-amd64.tar.gz
tar -xvzf kubeseal-${VERSION}-linux-amd64.tar.gz
sudo mv kubeseal /usr/local/bin/

kubeseal --version

secret 암호화

방법1) k8s api server로 암호화

kubeseal --controller-name=sealed-secrets --controller-namespace=sealed-secrets --format yaml < secret.yaml > sealed-secret.yaml

방법2) PEM키로 암호화

# public-cert.pem 추출
kubeseal --fetch-cert --controller-name sealed-secrets --controller-namespace sealed-secrets > pub-cert.pem

# 암호화
kubeseal --format yaml --cert pub-cert.pem < elice-file-api-secret.yaml > ks-elice-file-api-secret.yaml # Using Pem file

Git으로 PUSH!

GRE 터널링 + NAT 환경으로 외부통신 구현

록흐 — Tue, 21 Apr 2026 16:01:34 +0900

이슈

K8S 를 특정 클라우드 환경에 구현하다가 NAT 기능이 없는 것을 보고 NAT 기능을 해줄 VM이 필요하여 생성하였는데 이슈가 있었다. Client 서버(K8S Node)에서 NAT 서버로 정적 라우팅으로 트래픽을 foward하면 클라우드 환경 내부에서 비정상 패킷으로 감지하고 DROP 시키는 이슈가 있었다.

조치

NAT서버와 Client 서버 사이에 GRE 터널링을 적용하여 패킷을 캡슐화하고, 목적지 IP와 NIC의 MAC 주소 일관성을 유지함으로써 비정상 패킷으로 인한 DROP을 방지하고 NAT 기능을 구현하였다.

NAT 서버 설정

# IP 포워딩 영구 활성화 +.  리눅스가 “패킷 경로 이상하다”면서 버리는 걸 막는 설정(rp_filter)
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf
echo "net.ipv4.conf.all.rp_filter=0" >> /etc/sysctl.conf
echo "net.ipv4.conf.default.rp_filter=0" >> /etc/sysctl.conf
echo "net.ipv4.conf.enp0s3.rp_filter=0" >> /etc/sysctl.conf
sysctl -p

# NAT 규칙 ( enp0s3 = 외부 인터페이스 )
# SNAT ( 나가는 인터페이스(enp0s3) IP로 출발지 IP 변경 )
iptables -t nat -A POSTROUTING -o enp0s3 -j MASQUERADE 
iptables -A FORWARD -j ACCEPT

# iptables 영구 저장
apt install iptables-persistent -y  # ubuntu
netfilter-persistent save

NAT 서버 netplan

network:
    bonds: {}
    ethernets:
        ens1:
            addresses:
            - 192.168.0.5/24
            match:
                macaddress: 02:00:f9:80:19:4c
            mtu: 8950
            nameservers:
                addresses:
                - 8.8.8.8
            routes:
            -   to: default
                via: 192.168.0.1
    tunnels:
      gre1:
        mode: gre
        local: 192.168.0.5
        remote: 192.168.0.3
        ttl: 255
        addresses:
          - 172.16.100.1/30
      gre2:
        mode: gre
        local: 192.168.0.5
        remote: 192.168.0.4
        ttl: 255
        addresses:
          - 172.16.101.1/30
    version: 2

Client 서버1 netplan ( gre1 )

network:
    bonds: {}
    ethernets:
        ens1:
            addresses:
            - 192.168.0.3/24
            match:
                macaddress: 02:00:d4:67:47:37
            mtu: 8950
            nameservers:
                addresses:
                - 8.8.8.8
    tunnels:
      gre1:
        mode: gre
        local: 192.168.0.3
        remote: 192.168.0.5
        ttl: 255
        addresses:
          - 172.16.100.2/30
        routes:
          - to: default
            via: 172.16.100.1
    version: 2

Client 서버1 netplan ( gre2 )

network:
    bonds: {}
    ethernets:
        ens1:
            addresses:
            - 192.168.0.4/24
            match:
                macaddress: 02:00:75:42:ce:24
            mtu: 8950
            nameservers:
                addresses:
                - 8.8.8.8
    tunnels:
      gre1:
        mode: gre
        local: 192.168.0.4
        remote: 192.168.0.5
        ttl: 255
        addresses:
          - 172.16.101.2/30
        routes:
          - to: default
            via: 172.16.101.1
    version: 2

테스트

외부로 ping이 가고 apt update가 잘 되는 것을 확인

Pod 내부에서도 외부 통신 확인

영구적인 Service Account Token 만들기

록흐 — Wed, 4 Feb 2026 14:01:37 +0900

아래처럼 ServiceAccount에서 토큰을 추출하면 토큰만료기간이 정해져있어 보안에는 좋지만 관리가 쉽지 않다.

# 한시적인 Token 생성 
kubectl create token <ServiceAccount명> -n <namespace명> --duration=24h

토큰을 영구적으로 사용하려면 kubernetes.io/service-account-token 타입의 Secret을 생성하여 ControlPlane이 etcd에 저장된 Token을 만료시간을 reconciliation 하도록 해야한다.

To create a non-expiring, persisted API token for a ServiceAccount, create a Secret of type kubernetes.io/service-account-token with an annotation referencing the ServiceAccount. The control plane then generates a long-lived token and updates that Secret with that generated token data. ( https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/ )

Secret 생성

apiVersion: v1
kind: Secret
metadata:
  name: <SA이름>-token
  namespace: <네임스페이스>
  annotations:
    kubernetes.io/service-account.name: "<SA이름>"
type: kubernetes.io/service-account-token

Token 추출

ARGO_TOKEN="Bearer $(kubectl get secret <ServiceAccount명>.service-account-token -o=jsonpath='{.data.token}' | base64 --decode)"
echo $ARGO_TOKEN

node-core-dns 란?

록흐 — Wed, 31 Dec 2025 17:56:49 +0900

K8s에 떠있는 파드 하나에 내부로 접속해서 resolv.conf 파일을 열어보면 다음과 같다.

bash-4.4$ cat /etc/resolv.conf
search mongodb.svc.cluster.local svc.cluster.local cluster.local default.svc.cluster.local
nameserver 192.254.25.10
options ndots:5

kube-proxy는 svc -> pod 트래픽을 이동시킨다.

그러므로 만약 다른 파드로 트래픽을 보내고 싶다면 svc로 트래픽을 보내면 된다. svc의 도메인과 ip 매핑 정보는 CoreDNS에 저장되어 있는데, DNS 쿼리 성능을 높히기 위해, CoreDNS의 캐시를 가지고 있는 파드를 daemonset으로 배포하는데, 그것이 바로, 'node-core-dns' 이다.

https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/

각 파드는 nameserver ip로 192.254.25.10 설정되어 있는데, 192.254.25.10로 드러온 트래픽은 node-core-dns 파드로 전달되도록 kube-proxy가 설정해놓는다. ( iptables or ipvs )

$ ip addr | grep nodelocaldns
7: nodelocaldns: <BROADCAST,NOARP> mtu 1500 qdisc noop state DOWN group default
    inet 192.254.25.10/32 scope global nodelocaldns

그러므로 각 파드는 nodlocaldns에 질의를 날려야 한다.

bash-4.4$ cat /etc/resolv.conf
search mongodb.svc.cluster.local svc.cluster.local cluster.local default.svc.cluster.local
nameserver 192.254.25.10
options ndots:5

각 파드는 mongodb.svc.cluster.local svc.cluster.local cluster.local default.svc.cluster.local와 같이 일종의 Postfix(?)를 다양한 범위로 가지고 있다. 그래서 svc의 모든 도메인을 치지 않아도, systemd-resolved가 여러 시도를 수행한다.

monitoring 네임스페이스에 있는 grafana svc에 트래픽을 보내고 싶다면 [서비스명].[네임스페이스]만 설정해도 서비스의 ip를 dns로 부터 얻을 수 있다.

$ nc -zv monitoring-stack-grafana.monitoring 80
monitoring-stack-grafana.monitoring (10.233.13.144:80) open

참고자료

https://kubernetes.io/docs/tasks/administer-cluster/nodelocaldns/

[Terraform] 테라폼 동작원리 ( + Ansible )

록흐 — Fri, 26 Dec 2025 21:50:50 +0900

Terraform이 강력한 이유는 tfstate 파일로 인프라를 리소스 단위로 상태 관리를 하기 때문이다.

AWS, AZURE 같은 Public Cloud 환경은 여러 리소스 ( VPC, EC2 등 )이 서로 유기적으로 연동되어 있는데, 이를 '코드'로 구현하고 구현된 '상태'를 비교하여 어떤 인프라 요소가 생성, 변경, 삭제 되는지를 예측할 수 있다. 반면 대표적인 또 다른 배포도구인 Ansible은 상태를 관리하지 않는다.

상태를 관리하는 Terraform, 상태를 관리하지 않는 Ansible.

두 도구의 철학은 다르다.

Terraform은 비교로 인프라를 관리하고

Ansible은 명령으로 인프라를 관리한다.

Terraform은

내가 원하는 상태는 'EC2가 t3.small이야' 라고 말하면

테라폼은 실제 환경과 API로 통신하여 '실제 환경은 EC2가 t3.large네'라고 상태를 비교하여 변경,생성,삭제 지점을 파악한다.

Ansible은

'EC2를 t3.small로 변경해!' 라고 그냥 명령을 내리는 것이다.

Ansible은 직접 ssh로 접속해서 생성,변경,삭제 명령을 수행한다.

그러므로

Code를 절차적으로 실행해서 인프라 환경을 구성하는 작업은 Ansible이 유리하고 ( OS 설정 같은 내부작업 )

AWS, Azure 인프라 환경 같이 여러 리소스가 유기적으로 연결되어 있는 인프라의 생성 및 관리는 테라폼이 유리하다.

한마디로 정리하면, 테라폼은 '과거'를 기억한다.

테라폼 동작 원리

테라폼은 과거를 '장부'에 기록하는데, 그것이 tfstate 파일이다.

왜 장부(tfstate)가 필요할까?

어떤 Engineer가 good_ec2라는 이름을 가진 EC2 서버의 설정을 변경하는 코드를 작성했다 가정하자. 그러나 실제환경인 AWS는 good_ec2가 뭔지 모른다. good_ec2는 사람이 이해할 수 있는 이름이므로 EC2를 특정지을 수 없다. 또 다른 누군가가 특정 EC2를 good_ec2로 네이밍할 수도 있는것이다. 특정 지을수 없다면 추적되지 못하므로 지속적 관리가 불가능해진다. ( Ansible처럼 일회성으로 생성, 변경, 삭제가 목적이라면 모를까... )

미래와 현재 사이에 과거를 기억하는 tfstate를 두어보자.

Engineer가 good_ec2를 최초 생성할때 tfstate에는 good_ec2가 어떤 EC2인지 특정지을 수 있는 ID와 매핑되어 기록된다. Engineer가 good_ec2를 변경하려한다면 테라폼은 tfstate를 읽어 해당 EC2의 상태를 API로 호출하여 비교한다.

여기서 tfstate의 기록을 현재(실제환경)에서 API로 호출하여 최신화하는 작업을 refresh 라고한다.

'terraform plan'을 실행하면 미래 와 현재를 비교한다. tfstate에 기록된 대상들을 임시로 refresh하여 현재상태로 만들고 수정된 코드와 비교한다 . ( apply가 아닌 plan이므로 실제 tfstate가 최신화되는 것은 아님, 임시로... )

현재에는 없는데 미래에 있으면 생성(Create)

현재에도 있고 미래에도 있으면 변경(Update)

현재에는 있는데 미래에 없으면 삭제(Delete)

모든 것은 상태가 기록된 tfstate를 기준으로 동작하므로, tfstate는 정말 중요하다.

실제 환경에 인프라가 구성되어 있는데, tfstate를 지워버리면 어떻게 될까?

테라폼은 tfstate를 기준으로 refresh하여 현재 코드와 실제환경을 비교하므로, tfstate가 없다면 코드로 작성된 모든 리소스는 신규 생성 대상이 된다. 이미 인프라가 모두 구성되어 있는데, 동일한 인프라가 중복되어 또 다시 생성되는 것이다. 이렇듯 tfstate는 항상 최신상태를 유지하도록 관리되어야 하므로, 여러 사람이 동시에 테라폼코드를 수정하는 상황을 잘 제어해야 한다.

테라폼 배포과정

코드 작성(tf파일 생성) > init > validate > plan > apply

terraform init

init은 테라폼 초기환경을 구성한다.

코드에 작성한 API를 호출하는 프로바이더에 대한 정보가 명시된 .terraform.lock.hcl 파일을 생성하고 프로바이더 바이너리 파일을 설치한다. .terraform.lock.hcl 파일은 설치한 프로바이더에 대한 정보가 명시되어 있다. .terraform.lock.hcl 파일을 git으로 공유하면 다른 팀원이 init 시, .terraform.lock.hcl 파일에 명시된 프로바이더를 설치한다.

이외에도 선언한 모듈들의 소스를 로컬로 가져오거나 tfstate를 어디에 저장할 것인가에 대한 여러 설정을 초기화 한다.

terraform validate

작성된 소스들의 테라폼 문법을 검사하는 과정이다.

terraform plan

tfstate 파일을 임시로 refresh하여 테라폼 코드와 상태를 비교하는 과정이다.

terraform apply

실제 환경으로 배포가 되는 과정이다. 배포가 완료되면 tfstate 파일은 refresh되어 현재 상태가 기록된다.