셀프 호스팅 배포 문제 해결(Troubleshooting Self-Hosted Deployments)
셀프 호스팅 배포 문제 해결(Troubleshooting Self-Hosted Deployments)
이 페이지는 차트·애플리케이션 수준에서 모든 클라우드에 공통적인 이슈를 다뤄요. 플랫폼 특정적인 로드 밸런서, 인그레스, 인증서 문제는 해당 클라우드 Deploy 페이지의 Troubleshooting 섹션을 참고하세요: AWS, GCP, 또는 Azure.
출처: 문서
본문
먼저 볼 곳
파드 목록부터 시작하고, Running·Ready가 아닌 것들의 이벤트와 로그를 읽어요:
kubectl get pods -n confident-ai
kubectl describe pod <pod> -n confident-ai # events at the bottom
kubectl logs <pod> -n confident-ai # add -p for a crashed previous container
시작 순서는: ClickHouse 오퍼레이터, 그 다음 ClickHouse·Keeper, 마이그레이션 작업, 그 다음 앱 파드예요. 그 체인 초반의 실패는 흔히 뒤의 파드가 대기하는 것으로 나타나요.
일반적인 이슈
| 증상 | 원인과 조치 |
|---|---|
| 마이그레이션 작업이 실패하거나 crash-loop | PostgreSQL이나 ClickHouse에 도달하지 못하거나 자격 증명이 틀렸어요. DATABASE_URL과 ClickHouse 비밀번호(clickhouse.password)가 설정됐는지 확인하세요. 작업 로그 읽기: kubectl logs job/confident-migrations -n confident-ai. |
앱 파드가 CreateContainerConfigError에 머무름 |
앱 Secret이 아직 없어요. 보통 External Secrets Operator가 동기화하지 않았기 때문이에요. kubectl get externalsecret -n confident-ai가 SecretSynced를 보이면 스스로 복구돼요. |
ExternalSecret이 SecretSynced에 도달하지 못함 |
ESO가 클라우드 시크릿 스토어를 읽지 못해요. 시크릿 스토어 플래그가 Terraform에서 활성화됐는지, external-secrets-sa 서비스 계정이 올바른 클라우드 아이덴티티에 바인딩됐는지 확인하세요 (클라우드 Deploy 페이지 참고). |
앱 이미지에서 ImagePullBackOff |
풀 시크릿이 없거나 만료됐어요. imagePullSecretRefresh.enabled와 Confident AI의 ECR 자격 증명이 올바른지 확인하세요. |
프론트엔드가 ENOTFOUND confident-backend로 500을 반환 |
프론트엔드가 차트 접두사 이름으로 백엔드 서비스를 확인해요. fullnameOverride: confident(차트 기본값)를 유지하세요. 바꾸지 마세요. |
ClickHouse Keeper가 Not authenticated 로그 |
이전 실패한 설치의 오래된 PersistentVolumeClaim이에요. helm uninstall, kubectl delete pvc -n confident-ai --all (데이터가 버려도 된다면), 그 다음 재설치하세요. |
ClickHouse가 Listen [::]... Address family not supported로 crash-loop |
노드가 IPv4 전용이에요. 차트가 이미 ClickHouse를 0.0.0.0으로 청취하도록 고정하므로, clickhouse.extraConfig를 오버라이드한 경우에만 나타나요. |
파드가 Pending에 갇히고, PVC가 바인딩되지 않음 |
기본 StorageClass가 없어요 (새 EKS에서 일반적). 하나를 만들고 clickhouse와 redis에 storageClass를 설정하세요. AWS Infrastructure 페이지 참고. |
| 초대된 사용자가 이메일을 받지 못하고, 비밀번호 재설정이 동작하지 않음 | 이메일 전송 수단이 설정되지 않았거나, 릴레이가 발신자를 거부했어요. email.from과 email.smtp.host(그리고 secrets.data.SMTP_PASSWORD), 또는 secrets.data.RESEND_API_KEY를 설정하고, email.from이 릴레이가 보낼 수 있는 주소인지 확인하세요. 백엔드는 구성되지 않았을 때 [EMAIL] Neither SMTP_HOST nor RESEND_API_KEY is set를 로그해요. 그때까지는 Team 페이지의 "Copy invitation link"로 초대 링크를 공유하세요. |
| 도메인이 502나 게이트웨이 오류를 표시 | 클라우드 로드 밸런서의 헬스 체크가 실패하고 있어요. 플랫폼별이므로 클라우드 Deploy 페이지의 Troubleshooting 섹션을 참고하세요. |
조각들을 개별로 확인
kubectl get externalsecret -n confident-ai # secret sync status
kubectl get chi,chk -n confident-ai # ClickHouse installation + Keeper
kubectl get ingress -n confident-ai # ingress address and backends
kubectl exec -it deploy/confident-backend -n confident-ai -- env | grep -E 'DATABASE_URL|CLICKHOUSE'
여전히 막혔다면
실패한 파드의 describe 출력과 로그를 모아 플랫폼 팀과 상담하세요. 차트 버전(image.tag)과 사용 중인 클라우드를 포함하세요.