트러블슈팅¶

make 단계별 에러 cheatsheet¶

증상	원인 / 대처
`make up` 도중 `UnauthorizedOperation`	AWS 자격증명/권한 부족. `aws sts get-caller-identity` 확인, 권한 부여
`make ssm` → `session-manager-plugin not found`	로컬에 플러그인 미설치. 설치 안내 참조
`make ssm` → `TargetNotConnected`	노드가 아직 SSM agent를 띄우는 중 (부팅 후 30초쯤). 다시 시도
`make osh-deploy`가 중간에 Failed	이어하기 참조
어떤 pod이 영원히 `Init:0/N` 또는 `0/1 Running`	함정 5가지 참조
`openstack server create`가 ERROR	`kubectl -n openstack logs -l application=nova,component=compute --tail=50` 보고, 보통 libvirt/qemu 자원 부족 또는 neutron 포트 생성 실패
처음부터 깨끗하게 시작	`make down` → 잠시 후 `make up`. terraform state는 자동 동기화

osh-deploy 진행도 확인 (20-30분 동안 어디까지 왔나)¶

make osh-deploy는 SSM run-command로 노드에서 osh/deploy.sh를 돌리는데, 로컬 터미널엔 30초마다 status 폴링만 보인다. 실제 진행 단계는 세 갈래로.

(1) SSM run-command의 실시간 stdout (set -x trace)¶

deploy.sh는 set -x로 켜져 있어서 지금 어느 helm install/kubectl apply 단계인지 줄 단위로 찍힌다. make osh-deploy 화면의 command-id를 잡아서:

aws ssm get-command-invocation \
    --command-id <command-id> \
    --instance-id <i-xxxx> \
    --region ap-northeast-2 \
    --query 'StandardOutputContent' --output text | tail -50

마지막 줄이 어떤 chart를 깔고 있는지 / 어떤 job을 기다리는지 알려준다.

(2) 노드 안에서 클러스터 상태 (가장 신뢰할 수 있음)¶

make ssm
sudo -i
export KUBECONFIG=/etc/kubernetes/admin.conf

helm -n openstack list          # 지금까지 성공한 release
kubectl -n openstack get pods   # 떠 있는 파드
kubectl -n openstack get jobs   # bootstrap job 진행 (Completions 1/1 = 끝)

helm list 줄 수가 늘어나는 속도 = 진행 속도. 보통 순서: rabbitmq → mariadb → memcached → keystone → glance → openvswitch → libvirt → placement → nova → neutron. 10개 채워지면 거의 끝.

(3) 가장 오래 걸리는 단계 — `nova-bootstrap`의 `wait_for_computes`¶

nova chart의 bootstrap job이 hypervisor(=nova-compute가 placement에 등록되는 것)가 잡힐 때까지 폴링한다. 여기서 5-10분 걸린다. 진행 상황을 보려면:

kubectl -n openstack get jobs | grep bootstrap
kubectl -n openstack logs job/nova-bootstrap -f --tail=30
# 또는
kubectl -n openstack logs job/keystone-bootstrap --tail=30

nova-compute 파드가 placement에 등록되면 (openstack hypervisor list에 나타나면) bootstrap job이 Succeeded로 빠지고 다음 helm install로 진행.

osh-deploy 중간 실패 시 이어하기¶

osh/deploy.sh는 idempotent하게 짜여 있다:

helm upgrade --install 사용 — 이미 깔린 release는 그대로
노드 라벨, StorageClass, namespace 등 모두 “이미 있으면 skip”
patch 명령들도 멱등

그래서 make osh-deploy 를 다시 호출하면 된다. 단, glance helm release가 failed 상태로 남는 경우가 가끔 있는데(post-install hook 이 지연되면) 이건 cosmetic 이라 무시해도 PVC·pods 는 정상이다.

진짜 깨졌다 싶으면:

make ssm
sudo -i
export KUBECONFIG=/etc/kubernetes/admin.conf
helm -n openstack uninstall <release-name>     # 막힌 chart만 제거
exit   # 로컬로 나와서
make osh-deploy

함정 5가지 (원인과 해결)¶

이 랩을 만들면서 실제로 부딪힌 것들. 모두 osh/deploy.sh와 terraform/user_data.sh에 영구 해결 코드가 들어있다.

#1 `helm osh` 플러그인이 다음 SSM 호출에서 사라짐¶

원인: SSM run-command 셸이 HOME=''로 시작. helm은 $HOME/.local/share/helm/plugins를 보는데 비어있으면 cwd 기준으로 보게 됨 → 매번 다른 디렉토리. 해결: 노드에서 도는 모든 스크립트가 첫줄에 export HOME=/root. → osh/deploy.sh:9.

#2 OSH의 `glance-images` PVC가 영원히 Pending¶

원인: glance 차트의 volume.class_name=general인데 클러스터 default StorageClass는 local-path. 해결: general이라는 이름으로 같은 provisioner(rancher.io/local-path)를 가리키는 StorageClass 추가. → osh/deploy.sh Step 4.

#3 `neutron-metadata-agent`가 Init:0/2에서 영원히 멈춤¶

원인: 차트의 init dependency가 Service metadata를 기다리는데, 그 Service의 selector는 {app: ingress-api}이고 ports는 80/443. 우리 클러스터엔 ingress 컨트롤러가 없어 selector match 없음 → endpoints 비어 있음. 해결: Service metadata의 selector를 nova-api-metadata 파드에 매치하도록 patch + targetPort를 8775로. → osh/deploy.sh Step 14.

#4 `nova-compute` / `neutron-l3-agent` / `neutron-dhcp-agent` DaemonSet이 0/1 Running으로 영원히¶

원인: health-probe.py가 oslo.messaging으로 RabbitMQ 호스트네임을 resolve 시도하는데 pod DNS 환경에서 timeout (Name or service not known). 실제 프로세스는 정상 — placement에 hypervisor 등록, neutron 에이전트 등록 다 잘 동작. 해결: 세 DaemonSet에서 startupProbe/readinessProbe/livenessProbe 모두 제거하고 rollout restart. → osh/deploy.sh Step 15.

#5 옛 user_data 주석의 stable 브랜치를 더 이상 안 함¶

원인: opendev.org/openstack/openstack-helm의 stable/2024.1 브랜치 자체가 삭제됨. master/edge 두 갈래 + release tag만 남음. 해결: release tag (2024.2.0)로 clone. → osh/deploy.sh Step 1.

#6 (보너스) baltocdn helm apt 저장소의 키 응답이 비어 옴¶

원인: 옛 helm 설치 가이드들은 https://baltocdn.com/helm/signing.asc를 apt-key로 받는데, 이 엔드포인트가 빈 응답을 줘서 gpg --dearmor가 “no valid OpenPGP data” 실패. 해결: 공식 https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 스크립트로 설치. → terraform/user_data.sh 6b 단계.