36 KiB
id, kind, slug, title, topic, topicName, project, status, studio, pinnedVersions, sourceRevision, source
| id | kind | slug | title | topic | topicName | project | status | studio | pinnedVersions | sourceRevision | source | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 7b113a04-180a-40ec-9270-033531c22221 | SETUP | keycloak-two-nodes-and-postgres-on-k3s | Keycloak 2노드와 PostgreSQL 을 k3s 에 올리고 클러스터가 묶였는지 확인한다 | lab-environment-build | 실험대 환경 구성 | virtualization | 게시 전 | https://hyeonworks.com/studio/documents/7b113a04-180a-40ec-9270-033531c22221/edit |
|
import-head 9465582b5d1630eb4ae7c4e078021486919bf6b6 · uncommitted-working-tree snapshot |
|
Keycloak 2노드와 PostgreSQL 을 k3s 에 올리고 클러스터가 묶였는지 확인한다
매니페스트 한 장을 apply 해 네임스페이스 keycloak-lab 에 Keycloak 두 대와 PostgreSQL 하나를 세우는 절차다. 세우는 명령은 두 줄이고, 나머지는 그 둘이 하나의 클러스터로 묶였는지 확인하는 명령이다.
배포 명령은 lab host의 kubectl에서 실행한다
이 단계는 앞의 셋보다 단순하다. 전부 [lab host] 에서 치고, 저장소 루트에서 친다. 마지막 로그인 확인만 브라우저다.
| 번호 | 무엇 | 어디서 |
|---|---|---|
| 1 | 매니페스트 적용 | [lab host] — ~/workspace/keycloak-pattern 안에서 |
| 2 | 파드 둘이 설 때까지 기다리기 | [lab host] |
| 판정 | 리소스 · 클러스터 · 밖에서 | [lab host] |
| 판정 | 관리 콘솔 로그인 | 브라우저 |
kubectl 이 lab host 에서 도는 까닭은 앞 단계에 있다. kubeconfig 를 게스트에서 호스트로 가져다 두었으므로 게스트에 들어갈 일이 없다. deploy/... 로 시작하는 상대경로는 저장소 루트 기준이라, 다른 디렉터리에서 치면 error: the path ... does not exist 로 막힌다.
이 단계에서 사용하는 리소스 정의는 저장소의 deploy/lab/k8s/keycloak-cluster.yaml에 들어 있다. 적용 전에 실제 매니페스트를 열어 이미지 태그와 Secret, PVC, Deployment 설정을 확인한다.
랩 호스트와 클러스터 내부의 이름 해석을 같은 것으로 보지 않는다. 랩 호스트에서 auth.hyeonworks.com을 풀면 자신의 tailnet 주소 100.83.212.4가 나오고, host가 스스로 낸 패킷은 iifname "tailscale0" DNAT 규칙을 타지 않으므로 이름 그대로 curl하면 실패할 수 있다. 그래서 lab host의 외부 경로 확인에는 --resolve <이름>:443:192.168.122.10으로 edge를 직접 짚는다.
클러스터 내부는 앞 단계에서 CoreDNS의 hyeonworks.com.server를 적용했다면 다르다. 2026-09-21 재검증에서는 적용 전 Keycloak 파드가 auth.hyeonworks.com → 100.83.212.4로 풀었고, 적용 뒤에는 192.168.122.10으로 바뀌었다. 따라서 현재 절차를 순서대로 밟았다면 파드 내부에서는 공개 이름이 edge를 가리켜야 한다. tailnet에 붙은 다른 기계에서는 DNS 이름 그대로 외부 진입 경로를 확인한다.
PostgreSQL 하나와 Keycloak 두 인스턴스를 올린다
가이드 05 의 「이 단계가 끝나면」은 두 줄이다.
https://auth.hyeonworks.com에서 관리 콘솔에 로그인되고, 두 Keycloak 이 하나의 클러스터로 보인다.
두 마디가 따로다. 「로그인된다」는 밖에서 잰 200 과 브라우저이고, 「하나의 클러스터로 보인다」는 아래 세 확인이다. 파드가 둘 다 Running 인 것과 하나의 클러스터로 묶인 것은 다르다.
| 무엇 | 값 |
|---|---|
| 네임스페이스 | keycloak-lab — 매니페스트 첫 문서가 kind: Namespace 라 apply 가 같이 만든다 |
| Keycloak | StatefulSet keycloak — 파드 keycloak-0 · keycloak-1 |
| PostgreSQL | Deployment postgres — ReplicaSet postgres-7b474b88c8 |
| Service | keycloak → Endpoints 10.42.0.67:8080,10.42.1.155:8080 |
| Secret | keycloak-lab-secrets — KC_BOOTSTRAP_ADMIN_PASSWORD 19 bytes · POSTGRES_PASSWORD 22 bytes |
| PVC | postgres-data 하나. StorageClass local-path — 파드 번호가 붙지 않는다(판정 ⑤) |
| Ingress | HOSTS 가 auth.hyeonworks.com |
| 클러스터링 | JGroups — 디스커버리 테이블 jgroups_ping, 메시지 포트 7800 |
| 관리 포트 | 9000 — /metrics 가 거기 있다 |
이미지 태그는 매니페스트가 갖는다. 가이드 05 는 그것을 적지 않았지만 2026-09-17 에 keycloak-pattern @ 9465582b 의 deploy/lab/k8s/keycloak-cluster.yaml 을 열어 읽었다.
image: postgres:16-alpine
image: quay.io/keycloak/keycloak:26.7.0
파드 자원 한도와 프로브 설정과 persistent-user-sessions 설정값은 아직 이 기록으로 옮기지 않았다.
PVC와 기존 namespace를 바꾸기 전에 확인한다
전제는 한 줄이다 — 앞 단계까지 끝나 https 가 열린다.
Keycloak과 PostgreSQL을 모두 제거하는 절차는 아직 검증하지 않았다. 이 단계는 keycloak-lab 네임스페이스와 그 안의 리소스를 만들며, local-path StorageClass를 사용하는 PVC 데이터는 노드 디스크에 놓인다. 네임스페이스와 PVC를 삭제했을 때 노드의 실제 데이터 디렉터리가 어떻게 정리되는지는 확인하지 않았다.
두 노드와 기본 StorageClass가 준비됐는지 확인한다
두 확인은 아무것도 바꾸지 않는다. 하나는 명령이 파일을 찾을 수 있는 곳인지 보고, 하나는 이 이름이 아직 Keycloak 이 아님을 확인한다.
확인 ① 지금 이 디렉터리에서 매니페스트가 보이는가
cd ~/workspace/keycloak-pattern
ls deploy/lab/k8s/
keycloak-cluster.yaml 과 observability.yaml 이 보이는가.
보이면 아래 kubectl apply -f deploy/... 가 파일을 찾는다. 안 보이면 첫 단계의 저장소 받기로 돌아간다 — 한 번 세웠다 철거한 뒤에는 VM 과 디스크만 지워지고 저장소는 각자 관리라 이 디렉터리가 없는 상태가 흔하다.
확인 ② 이 이름이 아직 Keycloak 이 아니다
curl -s -o /dev/null -w '%{http_code} tls=%{ssl_verify_result}\n' --resolve auth.hyeonworks.com:443:192.168.122.10 \
https://auth.hyeonworks.com/
앞 단계에서 잰 404 tls=0 이 그대로인가. 앞의 코드를 같이 본다.
tls=0 만 보면 안 된다. 연결이 아예 안 됐을 때도 tls=0 이 나온다 — %{ssl_verify_result} 는 TLS 검증까지 갔을 때만 뜻이 있고 못 갔으면 초기값 0 이 그대로 찍힌다. 2026-09-17 에 앞 단계를 건너뛴 상태에서 재 보니 이렇게 나왔다.
000 tls=0
000 은 응답이 없었다는 뜻이다. 판정은 코드가 404 인 것과 tls=0 이 같이 나오는 것으로 한다.
가이드가 그 값 옆에 한 줄을 적어 두었다 — 앞의 404 는 이 단계 이후에 200 으로 바뀐다. 지금 재 두면 아래의 200 이 이 단계가 만든 변화인지가 분명해진다.
PostgreSQL과 Keycloak을 순서대로 배포한다
1. 매니페스트 한 장을 적용한다
목적 — 네임스페이스부터 Ingress 까지 한 파일로 세운다.
cd ~/workspace/keycloak-pattern
kubectl apply -f deploy/lab/k8s/keycloak-cluster.yaml
정상이면 만든 객체가 줄마다 찍힌다. 파드가 서는 것은 그다음이라 이 출력만으로 끝났다고 판정하지 않는다.
네임스페이스를 따로 만들지 않는다. 매니페스트 첫 문서가 kind: Namespace 라 apply 가 같이 만들고, kubectl create namespace 를 먼저 치면 두 번째 실행부터 AlreadyExists 로 막힌다.
실패하면 적용 자체가 거절되면 클러스터가 서 있는지부터 본다. 앞 단계의 kubectl get nodes 가 두 줄을 내는지가 전제다. error: the path ... does not exist 면 저장소 루트가 아닌 곳에서 쳤다.
2. 두 파드가 다 설 때까지 기다린다
목적 — Keycloak StatefulSet 의 파드 둘이 Ready 가 될 때까지 다음 명령을 치지 않는다.
kubectl -n keycloak-lab rollout status statefulset/keycloak --timeout=300s
정상이면 2026-09-17 에 갓 세운 클러스터에서 잰 것이다.
Waiting for 2 pods to be ready...
Waiting for 1 pods to be ready...
partitioned roll out complete: 2 new pods have been updated...
마지막 한 줄에서 complete 라는 낱말과 파드 개수 2 를 본다. 그 줄이 나올 때까지 명령이 안 끝나고 멈춰 있는 것이 정상이다. 다만 아무것도 안 찍고 멈춰 있지는 않다 — Waiting for … 줄은 진행 상황이지 오류가 아니다. 숫자가 줄어들수록 파드가 하나씩 Ready 가 된다. StatefulSet 은 파드를 하나씩 순서대로 띄우므로 중간에 0/2 로 한참 멈춰 있는 것도 정상이다.
300초를 다 쓰고 타임아웃으로 끝나면 그것도 답이 된다. 「안 떴다」가 확정되고 진단으로 넘어간다. rollout status 를 쓰는 까닭은 get pods 를 반복해서 치는 것보다 나아서만이 아니라, 언제 끝났는지를 사람이 판정하지 않아도 되기 때문이다. 기다리지 않고 판정으로 가면 아직 안 뜬 것과 못 뜨는 것이 섞인다.
실패하면 타임아웃으로 끝났으면 아래 「막히면」의 순서대로 본다.
replica·DB·Service에 사용한 값
만들어지는 객체는 「이 단계가 세우는 것」의 표에 있고, 여기서는 그 값들이 어디서 왔는지를 적는다.
| 값 | 어디서 정해지나 |
|---|---|
| 네임스페이스 이름 | 매니페스트 첫 문서 |
| 파드 이름의 순번 | StatefulSet 이라 keycloak-0 · keycloak-1 |
| 파드 이름의 해시 | Deployment 가 만든 ReplicaSet 이름에서 물려받는다 |
| Secret 의 바이트 수 | 매니페스트가 넣은 값의 길이. 실제 비밀 값은 출력하지 않는다 |
| PVC 가 붙는 노드 | local-path 가 파드 스케줄을 기다렸다 그 노드에 만든다 |
| Ingress 의 HOSTS | 앞 단계에서 발급한 인증서의 이름과 같아야 한다 |
Ingress 의 호스트 이름이 인증서의 이름과 다르면, 밖에서는 TLS 는 되는데 404 가 나온다.
Keycloak 두 파드와 클러스터 형성을 확인한다
kubectl get pods 만 보면 놓치는 것이 많다. 위에서 아래로 확인한다.
확인 ① 무엇이 만들어졌나
이 네임스페이스에 무엇이 서 있는지.
kubectl -n keycloak-lab get all
kubectl -n keycloak-lab get secret,configmap,pvc,ingress
① 은 종류별로 묶여 나오는 왼쪽 이름 열을 훑고, 파드 줄에서는 READY 칸의 1/1 과 RESTARTS 칸을 본다. RESTARTS가 0이 아니면 현재 Running 상태더라도 컨테이너가 이전에 재시작된 기록이 있다는 뜻이다. ② 는 네 종류가 하나씩이라도 있는가, PVC 줄의 STATUS 가 Bound 인가, Ingress 줄의 HOSTS 칸이 auth.hyeonworks.com 인가.
get all 은 이름과 달리 전부가 아니다. Secret 과 ConfigMap 과 PVC 와 Ingress 가 ① 의 출력에 나오지 않으므로, 첫 명령만 보고 「다 만들어졌다」로 판정하면 빠진 것을 모른 채 다음으로 간다. 매니페스트에 있는데 ② 에 없는 종류가 있다면 apply 가 부분적으로만 먹었다.
확인 ② Deployment 에서 ReplicaSet 을 지나 파드까지 이어졌나
사슬 어디까지 갔는지. Deployment 는 파드를 직접 만들지 않고 ReplicaSet 을 만들며 그것이 파드를 만든다.
kubectl -n keycloak-lab get rs,pod -l app=postgres
실측 — 2026-09-11
NAME DESIRED CURRENT READY AGE
replicaset.apps/postgres-7b474b88c8 1 1 1 80m
NAME READY STATUS RESTARTS AGE
pod/postgres-7b474b88c8-ll87p 1/1 Running 0 80m
ReplicaSet 이름의 해시가 파드 이름 가운데 해시와 같은가, 그리고 DESIRED 와 CURRENT 와 READY 세 숫자가 다 1 인가.
이 출력에 Deployment 줄이 없는 것도 정상이다. 이 매니페스트는 app: postgres 라벨을 파드 템플릿에만 달았고, ReplicaSet 과 파드는 템플릿에서 라벨을 물려받지만 Deployment 는 물려받지 않는다. Deployment 를 보려면 라벨 없이 친다.
kubectl -n keycloak-lab get deploy
StatefulSet 쪽은 사슬이 한 마디 짧다. ReplicaSet 을 만들지 않고 파드를 직접 만들어서 keycloak-0 처럼 순번 이름이 붙는데, 해시를 끼워 넣을 중간 객체가 없기 때문이다. 이름이 고정이라 같은 이름의 파드가 둘일 수 없고, 그래서 Terminating 파드가 안 지워지면 대체 파드도 안 생긴다. 가이드는 그 성질이 어느 실험에서 어떻게 나타나는지까지 적어 두었는데 그 실험 문서는 여기 반입되지 않았고, 이 실험대가 그 상태를 재현해 본 적도 없다.
kubectl -n keycloak-lab get sts,rs,pod -l app=keycloak
NAME READY STATUS RESTARTS AGE
pod/keycloak-0 1/1 Running 0 19m
pod/keycloak-1 1/1 Running 0 19m
배포를 여러 번 한 Deployment 는 ReplicaSet 이 여러 개 쌓인다. 새로 만들고 옛것은 0 으로 남기기 때문이고, 그래서 kubectl rollout undo 가 가능하다. 파드가 옛 해시를 달고 있으면 새 배포가 아직 안 넘어온 것이고, 그 상태로 실험하면 고친 적 없는 코드를 재게 된다.
| 무엇이 보이나 | 어디를 보나 |
|---|---|
| Deployment 는 있는데 RS 가 없다 | 컨트롤러가 못 돌았다 — RBAC·admission 확인 |
| RS 는 있는데 DESIRED 만 있고 CURRENT 가 0 | 파드를 못 만든다 — 이벤트를 본다 |
Pod 은 있는데 0/1 |
컨테이너가 안 뜬다 — 로그와 describe |
확인 ③ Secret 이 파드까지 이어졌나
값이 있는 것과 파드가 그 값을 받은 것은 다르다. 세 확인 모두 값을 찍지 않고 길이만 본다.
kubectl -n keycloak-lab describe secret keycloak-lab-secrets
실측 — 아래쪽 Data 절만 옮겼다
Data
====
KC_BOOTSTRAP_ADMIN_PASSWORD: 19 bytes
POSTGRES_PASSWORD: 22 bytes
kubectl -n keycloak-lab get secret keycloak-lab-secrets \
-o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d | wc -c
kubectl -n keycloak-lab exec keycloak-0 -- \
sh -c 'echo "길이=${#KC_BOOTSTRAP_ADMIN_PASSWORD}"'
길이=19
① 은 Data 절의 키 이름과 그 옆의 바이트 수 두 칸, ② 와 ③ 은 숫자 하나다. 세 수가 서로 같은가.
describe 는 값을 절대 찍지 않고 길이만 보여 주므로 키 목록 확인과 「비어 있지 않은가」 확인이 한 명령으로 끝난다. 세 수가 같으면 Secret 에서 파드 환경변수까지 이어졌다. 길이=0 이면 Secret 에는 있는데 이 파드가 그것을 안 받은 것이라, envFrom 이나 valueFrom 을 빠뜨렸거나 파드가 Secret 을 고치기 전에 떠서 옛 값을 들고 있다. 환경변수로 주입한 Secret 은 값을 바꿔도 파드를 다시 만들기 전까지 갱신되지 않는다. 바이트 수가 뜻밖에 크면, 이를테면 20 이어야 할 것이 21 이면 만들면서 개행이 같이 들어간 것이고 증상은 「비밀번호가 틀렸다」로 나온다. 매니페스트가 기대하는 키 이름이 하나라도 다르면 파드는 CreateContainerConfigError 로 멈추고, 까닭은 describe pod 의 Events 에 키 이름까지 적혀 나온다.
-o yaml 로 보지 않는다. base64 는 암호화가 아니라 인코딩이라 화면과 스크롤백과 화면 공유와 터미널 로그에 값이 그대로 찍힌다.
어느 환경변수가 어느 Secret 에서 왔는지도 볼 수 있다.
kubectl -n keycloak-lab get pod keycloak-0 \
-o jsonpath='{range .spec.containers[0].env[*]}{.name}{"\t"}{.valueFrom.secretKeyRef.name}{"\n"}{end}'
KC_DB
KC_DB_URL
KC_DB_USERNAME
KC_DB_PASSWORD keycloak-lab-secrets
KC_HOSTNAME
KC_HOSTNAME_STRICT
KC_PROXY_HEADERS
KC_HTTP_ENABLED
KC_HEALTH_ENABLED
KC_METRICS_ENABLED
JAVA_OPTS_KC_HEAP
KC_BOOTSTRAP_ADMIN_USERNAME
KC_BOOTSTRAP_ADMIN_PASSWORD keycloak-lab-secrets
2026-09-17 실제 출력은 열세 줄이었고 오른쪽이 채워진 줄은 둘이었다. 처음에는 앞의 네 줄만 실었는데 그러면 KC_BOOTSTRAP_ADMIN_PASSWORD 가 Secret 에서 오는 것이 안 보인다.
오른쪽 칸이 채워진 줄만 Secret 을 참조한다. 비밀이어야 할 변수의 오른쪽이 비어 있으면 그 값은 매니페스트에 평문으로 적혀 있다는 뜻이고, 그 파일은 대개 git 에 들어간다.
확인 ④ Service 뒤에 파드가 있나
Service 가 있어도 셀렉터가 안 맞으면 뒤가 비어 있다.
kubectl -n keycloak-lab describe svc keycloak | grep -i endpoints
Endpoints: 10.42.0.67:8080,10.42.1.155:8080
쉼표로 갈린 주소가 몇 개인가, 그 IP 들이 파드 IP 와 같은가, 포트 번호가 컨테이너가 실제로 듣는 포트인가.
두 개면 Service 가 두 파드를 다 잡고 있다. 비어 있으면 Service 는 있는데 뒤가 없는 것이고, 이때 증상이 「연결은 되는데 응답이 없다」라 원인이 Service 에 있다는 것을 알아보기 어렵다. 하나뿐이면 나머지 한 파드가 readiness 를 통과하지 못한 것이라, 그 상태로 이중화 실험을 시작하면 이미 한쪽으로만 가고 있던 트래픽을 이중화 실패로 오독하게 된다.
목록으로 보려면 EndpointSlice 를 쓴다.
kubectl -n keycloak-lab get endpointslice -l kubernetes.io/service-name=keycloak
NAME ADDRESSTYPE PORTS ENDPOINTS AGE
keycloak-xdph6 IPv4 8080 10.42.0.67,10.42.1.155 3d23h
kubectl get endpoints 는 쓰지 않는다. Kubernetes v1.33부터 deprecated 처리됐고, 이 실험대의 k3s 는 v1.36.4+k3s1 이라 그 조건에 해당한다. 이 deprecation 자체는 쿠버네티스 쪽 규격이다. 옛 문서와 블로그에 그 형태가 많다.
준비 상태까지 함께 보려면 이렇게 뽑는다.
kubectl -n keycloak-lab get endpointslice -l kubernetes.io/service-name=keycloak \
-o jsonpath='{range .items[*].endpoints[*]}{.addresses[0]}{"\t"}{.conditions.ready}{"\n"}{end}'
10.42.0.67 true
10.42.1.155 true
ready 가 false 면 파드는 있는데 readiness 프로브를 통과하지 못한 것이라 Service 가 그 파드로 트래픽을 보내지 않는다. 비어 있으면 셀렉터와 파드 라벨이 안 맞는다.
kubectl -n keycloak-lab get svc keycloak -o jsonpath='{.spec.selector}'; echo
kubectl -n keycloak-lab get pods --show-labels
확인 ⑤ PVC 가 실제로 붙었나
볼륨이 실제로 잡혔는지.
kubectl -n keycloak-lab get pvc
STATUS 칸이 Bound 인가 Pending 인가, VOLUME 칸이 비어 있는지, STORAGECLASS 칸이 local-path 인가.
이 실험대에는 파드 번호가 붙은 PVC 가 없다. 「StatefulSet 이면 PVC 이름 끝에 파드 번호가 붙는다」는 volumeClaimTemplates 를 쓰는 StatefulSet 의 이야기이고 이 매니페스트의 keycloak StatefulSet 에는 그 칸이 없다. PVC 는 PostgreSQL 이 쓰는 postgres-data 하나뿐이고 그것도 StatefulSet 이 아니라 별도 문서로 선언되어 Deployment 가 claimName 으로 가리킨다. 2026-09-17 에 매니페스트와 클러스터 양쪽에서 확인했다.
NAME STATUS VOLUME CAPACITY STORAGECLASS
postgres-data Bound pvc-fe269834-3dd1-4b1f-82f6-a53413310a30 5Gi local-path
Keycloak 파드에는 별도 영구 볼륨을 연결하지 않았다. 파드 로컬 파일시스템은 영구 저장소로 사용하지 않으며, PostgreSQL 데이터는 postgres-data PVC에 남는다.
Bound 면 볼륨이 붙었다. Pending 이면 StorageClass 가 없거나 노드에 자리가 없다. local-path 는 파드가 스케줄될 때까지 기다리므로, 파드가 안 뜨면 PVC 도 Pending 인 것이 정상이다. 둘이 서로를 기다리는 것처럼 보이지만 파드 쪽 원인을 먼저 본다. 사유는 PVC 의 이벤트에 적혀 있다.
kubectl -n keycloak-lab describe pvc
각 PVC 절의 맨 아래 Events 에 waiting for first consumer 인지 no persistent volumes available 인지가 적혀 있고, 둘은 대응이 다르다 — 앞엣것은 파드를 고치는 문제, 뒤엣것은 저장소를 고치는 문제다.
확인 ⑥ 클러스터가 묶였나 — 셋이 서로 다른 것을 말한다
두 Keycloak 이 하나의 클러스터로 묶였는지. 셋이 각각 다른 시점을 말한다. 로그는 「그때 그렇게 보였다」이고, 테이블은 「지금 등록되어 있다」이며, 지표는 「지금 그 노드가 그렇게 안다」이다.
kubectl -n keycloak-lab logs keycloak-0 | grep ISPN000094 | tail -1
ISPN000094: Received new cluster view for channel ISPN:
[keycloak-0-10001|1] (2) [keycloak-0-10001, keycloak-1-52537]
세 군데다. 괄호 안의 (2) 가 멤버 수, 대괄호 안의 이름 목록, 그리고 |1 이 뷰 번호다. 뷰 번호는 멤버가 들고 날 때마다 올라간다.
이름 뒤에 (v=…) 가 붙어 나오기도 한다. 2026-09-17 에 새로 세운 클러스터에서 같은 줄을 뽑아 보니 이랬다.
[keycloak-1-3159(v=16.0.12)|1] (2) [keycloak-1-3159(v=16.0.12), keycloak-0-13057(v=16.0.12)]
(v=16.0.12) 는 JGroups 가 붙인 판 번호이고, 볼 것은 그대로 (2) 와 이름 목록과 |1 이다. 맨 앞의 이름이 keycloak-0 이 아니어도 정상이다 — 맨 앞에는 코디네이터가 오고 먼저 뜬 쪽이 그 일을 맡는다. 이 판에서는 keycloak-1 이었다.
이름 목록의 keycloak-0-10001 은 파드 이름 그대로가 아니다. Infinispan 이 파드 이름 뒤에 임의의 접미사를 붙여 클러스터 노드 식별자로 쓰기 때문에, 아래 지표에 나오는 keycloak-0-46674 와는 keycloak-0 까지만 같다. 그래서 대조할 때 맞춰 보는 것은 접미사 앞의 파드 이름이다. Keycloak 만 StatefulSet 이라 그 앞부분이 고정이고, 덕분에 로그와 jgroups_ping 테이블과 지표를 같은 이름으로 견줄 수 있다.
(2) 면 이 노드는 상대를 봤다. (1) 이면 혼자 있다고 알고 있다. 뷰 번호가 계속 오르고 있으면 멤버가 붙었다 떨어지기를 반복하는 중이라, 「지금 2 다」라는 스냅숏보다 그 사실이 더 중요하다. 이 줄은 과거형이므로 지금 상태는 지표로 본다.
kubectl -n keycloak-lab exec deploy/postgres -- \
psql -U keycloak -d keycloak -c 'select name, ip from jgroups_ping'
행이 몇 개인가, 그리고 ip 칸이 확인 ④ 에서 본 파드 IP 와 같은가를 본다. 이 표는 「등록되어 있다」이지 「서로 말이 통한다」가 아니다. 두 행이 다 있는데 로그가 (1) 이면 서로를 찾기는 했는데 7800 포트로 메시지가 안 가는 것이고, 이 실험대에서 실제로 그 일이 벌어졌다. 옛 파드의 행이 남아 있을 수도 있으므로 IP 를 지금 파드와 대조한다.
kubectl -n observability exec deploy/prometheus -- \
wget -qO- 'localhost:9090/api/v1/query?query=vendor_cluster_size'
실측 — 줄바꿈 없는 JSON 한 줄에서 읽어낸 값이다
keycloak-1 → 2
keycloak-0 → 2
응답은 줄바꿈 없는 JSON 한 덩어리로 온다. data.result 배열에서 원소가 몇 개인가, 각 원소에서 metric 안의 node 라벨과 value 배열의 둘째 원소만 읽는다. 이 실험대에는 jq 가 없으므로 파서를 따로 짜지 말고 화면에 나온 JSON 을 그대로 읽는다. 원소가 하나뿐이면 나머지 노드의 스크레이프가 실패한 것이라 클러스터 문제가 아니라 관측 문제일 수 있다. 각 노드가 자기가 아는 멤버 수를 보고하므로 한 노드만 보면 분단을 놓친다 — 분단되면 한쪽은 2, 다른 쪽은 1 이 된다.
:::warning
Keycloak 컨테이너에는 curl 이 없다. 공식 이미지가 최소 구성이라 wget 도 nc 도 없고, 안에서 치면 command not found 와 exit code 127 로 끝난다.
:::
sh: line 1: curl: command not found
command terminated with exit code 127
Prometheus 가 아직 없으면 임시 파드를 띄운다.
K0=$(kubectl -n keycloak-lab get pod keycloak-0 -o jsonpath='{.status.podIP}')
kubectl -n keycloak-lab run m --rm -i --restart=Never \
--image=curlimages/curl:8.11.1 --quiet --command -- \
sh -c "curl -s http://$K0:9000/metrics | grep '^vendor_cluster_size'"
vendor_cluster_size{cache_manager="keycloak",node="keycloak-0-46674"} 2.0
줄 끝의 숫자와 중괄호 안 node 라벨이 어느 파드인가를 본다. 이 형태는 그 파드 하나에게 직접 물은 것이라 라벨의 노드 이름과 고른 파드가 반드시 일치한다. --rm 을 붙였으므로 파드는 끝나면 사라진다. 값이 안 나오고 연결 거부가 나면 관리 포트 9000 이 안 열렸다.
확인 ⑦ 밖에서 닿나
nginx 에서 Traefik, Ingress, Service 를 지나 파드까지 전부 이어졌는지.
curl -s -o /dev/null -w '%{http_code}\n' --resolve auth.hyeonworks.com:443:192.168.122.10 \
https://auth.hyeonworks.com/realms/master
200
코드 한 칸. 여기서 값만 뽑는 형태를 쓰는 것은 앞 두 단계에서 잰 것과 같은 명령으로 같은 값이 나오는지 비교하는 것이 목적이기 때문이다.
200 이면 2홉이 다 이어졌다. 502 나 503 이면 뒤에서부터 되짚는다 — Ingress 가 있는지(확인 ①), Service 뒤에 파드가 있는지(확인 ④), 파드가 Ready 인지(확인 ②) 순서다. 처음 보는 오류라 헤더가 필요하면 읽는 형태로 바꾼다.
curl -I --resolve auth.hyeonworks.com:443:192.168.122.10 https://auth.hyeonworks.com/realms/master
이 200 은 앞 단계를 끝냈을 때의 값이다. 인증서 단계를 건너뛰고 이 단계만 했다면 443 을 듣는 것이 없으므로 여기는 000 이다. 2026-09-17 에 그 상태에서 재 보니 이렇게 나왔다.
curl: (7) Failed to connect to auth.hyeonworks.com:443 after 2 ms: Could not connect to server
그때도 이 단계가 세운 것까지는 잴 수 있다. TLS 를 빼고 Host 헤더를 실어 80 으로 치면 nginx → Traefik → Ingress → Service → 파드가 이어졌는지가 그대로 나온다. 둘 다 200 이었다.
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://192.168.122.10/realms/master
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: auth.hyeonworks.com' http://192.168.122.11/realms/master
앞엣것은 엣지 nginx 를 지나고 뒤엣것은 Traefik 에 바로 친다. 둘이 같으면 남은 것은 TLS 뿐이다.
확인 ⑧ 관리 콘솔에 로그인된다
가이드가 적은 「이 단계가 끝나면」의 앞 절반.
브라우저로 https://auth.hyeonworks.com/admin 에 들어가 관리자로 로그인한다. 비밀번호는 확인 ③의 Secret에 있으며 실제 값은 출력하지 않고 길이만 확인한다.
세션 저장 위치는 관리 콘솔 로그인 성공과 별개의 질문이다. DB 테이블 한 번 조회한 결과만으로 DB 저장 또는 메모리 저장을 확정하지 않는다. Keycloak 버전과 persistent-session 설정에 따라 저장 구조와 시점이 달라질 수 있기 때문이다.
원문에는 offline_user_session을 로그인 전후로 비교하는 확인이 남아 있지만, 현재 persistent-user-sessions 설정값과 해당 조회 결과를 이 기록에서 다시 대조하지 못했다. 현재 확인한 범위는 두 Keycloak 노드가 클러스터를 이루고 외부 요청과 관리 콘솔이 동작하는 것까지다. 세션 저장 위치와 파드 재시작 뒤 생존 여부는 별도 세션 실험의 증거로 판정한다.
Keycloak 두 노드 확인표
| 무엇 | 명령 | 통과 |
|---|---|---|
| 롤아웃 | kubectl -n keycloak-lab rollout status statefulset/keycloak --timeout=300s |
complete · 파드 2 |
| Service 뒤 | kubectl -n keycloak-lab describe svc keycloak | grep -i endpoints |
주소 두 개 |
| 클러스터 | … query=vendor_cluster_size |
원소 둘 · 값 둘 다 2 |
| 밖에서 | curl -s -o /dev/null -w '%{http_code}\n' https://auth.hyeonworks.com/realms/master |
200 |
파드가 Pending이거나 두 인스턴스가 묶이지 않을 때
가이드 05 가 순서를 정해 두었다. 로그부터 보지 않는다.
① 이벤트부터. 스케줄링과 이미지와 볼륨 실패가 여기 나온다.
kubectl -n keycloak-lab get events --sort-by=.lastTimestamp | tail -20
맨 아랫줄부터 거꾸로 읽는다. --sort-by 를 준 까닭이 그것이다. TYPE 이 Warning 인 줄, REASON 칸, 그리고 OBJECT 칸이 어느 파드인가를 본다. 이벤트는 기본 한 시간만 남으므로 아무것도 없다고 문제가 없는 것은 아니다. REASON 하나가 다음 행동을 정한다 — FailedScheduling 은 노드에 자리가 없는 것이라 파드가 아니라 클러스터를 봐야 하고, ErrImagePull 은 이미지 이름 문제라 로그를 볼 것도 없으며, BackOff는 컨테이너가 시작 후 반복 종료되는 상태이므로 ③의 로그 확인으로 간다.
② describe. 그 파드에 한정된 이벤트와 상태를 함께 본다.
kubectl -n keycloak-lab describe pod keycloak-0
위에서부터 세 곳이다. Conditions 절에서 Ready 가 False 인가, 컨테이너 절의 State 와 Last State 와 그 안의 Exit Code, 그리고 맨 아래 Events. Exit Code 는 그것만으로 말이 된다 — 137 은 OOM 이나 강제 종료, 1 은 애플리케이션이 스스로 끝낸 것, 127 은 명령을 못 찾았다는 뜻이다. 137 이면 로그에 아무 단서도 없을 수 있어 메모리 한도를 본다. Ready 만 False 이고 컨테이너는 살아 있으면 readiness 프로브 문제이므로 확인 ④ 로 돌아간다.
③ 로그. 컨테이너가 시작된 뒤 종료되는 경우를 확인한다.
kubectl -n keycloak-lab logs keycloak-0
kubectl -n keycloak-lab logs keycloak-0 --previous # 재시작 직전 로그
첫 명령에서는 마지막 줄들, 둘째 명령에서는 스택 트레이스의 맨 윗줄을 본다. Keycloak 은 기동에 성공하면 Keycloak ... started in 한 줄을 남기므로, 그 줄이 있는지 없는지가 기동 중과 기동 실패를 가른다. --previous 가 중요하다 — CrashLoopBackOff 면 지금 컨테이너는 방금 뜬 것이라 종료 원인은 이전 컨테이너 로그에서 확인한다. --previous 가 not found 를 내면 아직 한 번도 재시작하지 않은 것이고, 그러면 지금 로그가 곧 전부다.
④ 그래도 모르면 안에서 본다.
kubectl -n keycloak-lab exec -it keycloak-0 -- sh
| 증상 | 어디를 보나 |
|---|---|
파드가 Pending |
describe pod 의 Events — 스케줄 불가 사유 |
ImagePullBackOff |
이미지 이름과 태그. 자체 빌드면 두 노드 모두에 반입했는가 |
CrashLoopBackOff |
logs --previous |
Running 인데 0/1 |
readiness 프로브 실패. describe 의 Conditions |
| 밖에서 502 | Ingress 에서 Service 로, Service 에서 Endpoints 로 뒤를 본다 |
| 클러스터가 1로 보임 | 7800 이 막혔거나 디스커버리 실패. 확인 ⑥ 의 셋 다 |
AlreadyExists |
kubectl create namespace 를 먼저 쳤다. 매니페스트가 만든다 |
error: the path ... does not exist |
저장소 루트가 아닌 곳에서 쳤다 |
이 Keycloak 배포에서 실제로 확인한 범위
- 2026-09-11 의 ReplicaSet 과 파드 이름과 해시, Secret 의 19 와 22 bytes 와 주입된 길이 19 와 복호 길이 22, Endpoints 두 개와 EndpointSlice 의
ready두 줄,ISPN000094뷰 줄,vendor_cluster_size가 둘 다 2, 임시 파드가 읽은2.0, Keycloak 이미지에curl이 없다는 것과 exit code 127. - 디스커버리 테이블에는 둘 다 있는데 메시지가 안 가는 상태를 실제로 겪었다.
kubectl get endpoints의 v1.33 deprecation 은 쿠버네티스 쪽 규격이다. 이 실험대에서는 해당 버전 위에서 명령 선택에 반영했을 뿐, deprecation 자체를 측정한 것은 아니다.- Infinispan 이 파드 이름에 임의의 접미사를 붙여 클러스터 노드 식별자로 쓰는 것은 Infinispan 쪽 동작이다. 2026-09-17 실제 로그에는
keycloak-0-10001과keycloak-0-46674가 그런 형태로 나타났다. keycloak-cluster.yaml의 모든 필드를 여기 옮기지는 않았다. 파드 자원 한도, 프로브,persistent-user-sessions처럼 이 절차에서 직접 확인하지 않은 값은 실제 매니페스트에서 확인한다.get all과get deploy와get pvc와describe pvc와 디스커버리 테이블 조회와get events와describe pod와logs의 출력은 가이드가 봐야 할 줄만 적었고 값이 남아 있지 않다.local-pathPVC를 포함한 전체 제거 절차와 삭제 뒤 노드 디스크의 데이터 상태는 아직 확인하지 않았다.- 이 단계에는 「이 실험대는 이렇게 했다」와 「따라 하는 사람은」 두 갈래가 없다. 05 는 파일을 직접 쓰지 않고 저장소의 매니페스트를 적용한다.
- 2026-09-17 에 갓 세운 클러스터에서 이 절차를 처음부터 다시 밟았다. 같은 값이 다시 나온 것 —
postgres-7b474b88c8이라는 ReplicaSet 해시, Secret 의 19·22 bytes 와 주입된 길이 19·복호 길이 22, Endpoints 두 개와ready두 줄,jgroups_ping2 행, 임시 파드가 읽은vendor_cluster_size … 2.0, Keycloak 이미지에curl이 없다는 것과 exit code 127,kubectl get endpoints의 deprecation 경고. 파드 IP 와 Infinispan 접미사만 달랐다 — 그것들은 매번 새로 붙는다. - 같은 날 실제 출력에서 문서와 달랐던 것은 다음과 같다 —
rollout status가Waiting for …를 찍는다는 것, PVC 가postgres-data하나라는 것, 환경변수 목록이 열세 줄이라는 것,ISPN000094이름에(v=16.0.12)가 붙는다는 것, 인증서 단계를 건너뛰면 밖에서가000이라는 것. keycloak-cluster.yaml을keycloak-pattern@9465582b에서 읽었다. 이미지 태그는postgres:16-alpine과quay.io/keycloak/keycloak:26.7.0이다.