본문으로 건너뛰기

A.3. 문제 해결

로그인 문제​

토큰 인증 실패​

증상:

  • "토큰이 필요합니다" 오류 메시지
  • "유효하지 않은 토큰" 오류 메시지
  • 로그인 후 바로 로그인 페이지로 돌아감

원인:

  • 만료된 토큰 사용
  • 잘못된 토큰 형식
  • 권한이 부족한 토큰

해결 방법:

  1. 토큰 재발급

    # Karmada 토큰 생성
    kubectl -n karmada-system get secret karmada-console-secret -o jsonpath='{.data.token}' | base64 -d

  2. 토큰 형식 확인

    • 토큰이 올바르게 복사되었는지 확인
    • 앞뒤 공백이 포함되지 않았는지 확인
    • 토큰 전체가 복사되었는지 확인

  3. 토큰 권한 확인

    # ClusterRole 확인
    kubectl get clusterrolebinding -o wide | grep console

SSO 로그인 실패​

증상:

  • "SSO 초기화 중..." 화면에서 멈춤
  • SSO 로그인 버튼 클릭 후 오류 발생
  • Keycloak 리다이렉트 실패

원인:

  • Keycloak 서버 연결 불가
  • 잘못된 Keycloak 설정
  • 브라우저 쿠키/세션 문제

해결 방법:

  1. Keycloak 서버 상태 확인

    # Keycloak 서비스 상태 확인
    kubectl get pods -n keycloak

  2. 브라우저 캐시 삭제

    • 브라우저 쿠키 및 캐시 삭제
    • 시크릿/프라이빗 모드로 시도

  3. Keycloak 설정 확인

    • Realm 및 Client 설정 확인
    • Redirect URI 설정 확인

세션 만료​

증상:

  • 갑자기 로그인 페이지로 이동
  • API 요청 시 401 오류
  • "인증 정보가 만료되었습니다" 메시지

해결 방법:

  1. 페이지 새로고침 후 다시 로그인
  2. 토큰을 재발급하여 새로 로그인
  3. 브라우저의 시크릿 모드에서 로그인 시도

클러스터 연결 문제​

클러스터 상태가 NotReady​

증상:

  • 클러스터 목록에서 "NotReady" 상태 표시
  • 클러스터 카드에 빨간색 경고 표시
  • 해당 클러스터의 리소스 조회 불가

원인:

  • 멤버 클러스터와의 네트워크 연결 문제
  • 멤버 클러스터의 에이전트 문제
  • 컨트롤 플레인 인증서 만료

해결 방법:

  1. 네트워크 연결 확인

    # 컨트롤 플레인에서 멤버 클러스터 연결 테스트
    kubectl --kubeconfig=/path/to/member/kubeconfig cluster-info

  2. Karmada 에이전트 상태 확인

    # 멤버 클러스터에서 에이전트 상태 확인
    kubectl -n karmada-system get pods -l app=karmada-agent
    kubectl -n karmada-system logs -l app=karmada-agent --tail=50

  3. 클러스터 상태 상세 확인

    # Karmada 컨트롤 플레인에서 클러스터 상태 확인
    kubectl get cluster <cluster-name> -o yaml

클러스터가 목록에 표시되지 않음​

증상:

  • 새로 등록한 클러스터가 보이지 않음
  • 클러스터 수가 예상보다 적음

원인:

  • 클러스터 등록이 완료되지 않음
  • 권한 문제로 클러스터 조회 불가
  • API 캐시 문제

해결 방법:

  1. 클러스터 등록 확인

    # 등록된 클러스터 목록 확인
    kubectl get clusters

  2. 페이지 새로고침

    • 브라우저 새로고침 또는 새로고침 버튼 클릭

  3. 권한 확인

    • 사용 중인 토큰이 클러스터 조회 권한을 가지고 있는지 확인

정책 관련 문제​

전파 정책이 적용되지 않음​

증상:

  • PropagationPolicy 생성 후 리소스가 전파되지 않음
  • 바인딩 상태가 "Pending" 상태에서 변하지 않음
  • 특정 클러스터에만 전파되지 않음

원인:

  • Resource Selector가 리소스와 일치하지 않음
  • Cluster Affinity 설정 오류
  • 대상 클러스터가 NotReady 상태

해결 방법:

  1. Resource Selector 확인

    • API Version, Kind, Name이 정확한지 확인
    • 네임스페이스가 일치하는지 확인
    • Label Selector가 올바른지 확인

  2. 정책 조건 상태 확인

    • 정책 상세 페이지의 "조건" 탭 확인
    • False 상태의 조건이 있는지 확인
    • 오류 메시지 확인

  3. 바인딩 상태 확인

    # ResourceBinding 상태 확인
    kubectl get resourcebinding -n <namespace>
    kubectl describe resourcebinding <name> -n <namespace>

  4. Work 리소스 확인

    # Work 리소스 상태 확인
    kubectl get work -n karmada-es-<cluster-name>

오버라이드 정책이 적용되지 않음​

증상:

  • OverridePolicy 생성 후 리소스가 변경되지 않음
  • 특정 클러스터에서 오버라이드가 적용되지 않음

원인:

  • Resource Selector가 리소스와 일치하지 않음
  • Cluster Affinity가 올바르지 않음
  • 오버라이더 설정 오류

해결 방법:

  1. 오버라이더 설정 확인

    • 오버라이더 타입과 경로가 올바른지 확인
    • JSON 패치 형식이 정확한지 확인

  2. 정책 우선순위 확인

    • 동일한 리소스에 여러 정책이 적용되는 경우 우선순위 확인
    • ClusterOverridePolicy가 OverridePolicy보다 우선

  3. 멤버 클러스터에서 리소스 확인

    # 멤버 클러스터에서 실제 리소스 확인
    kubectl --kubeconfig=/path/to/member/kubeconfig get <resource> <name> -o yaml

정책 삭제 후에도 리소스가 남아있음​

증상:

  • PropagationPolicy 삭제 후에도 멤버 클러스터에 리소스 존재
  • 의도치 않은 리소스가 계속 유지됨

원인:

  • PreserveResourcesOnDeletion 설정이 활성화됨
  • 삭제 작업이 완료되지 않음

해결 방법:

  1. 정책 설정 확인

    • preserveResourcesOnDeletion 값 확인
    • 리소스 유지가 의도된 것인지 확인

  2. 수동 삭제

    # 멤버 클러스터에서 리소스 수동 삭제
    kubectl --kubeconfig=/path/to/member/kubeconfig delete <resource> <name>

워크로드 문제​

Pod 상태 오류​

일반적인 Pod 오류 상태:

상태설명해결 방법
ImagePullBackOff컨테이너 이미지를 가져올 수 없음이미지 이름, 레지스트리 접근 권한 확인
ErrImagePull이미지 풀 오류이미지 존재 여부, 네트워크 연결 확인
CrashLoopBackOff컨테이너가 반복적으로 충돌컨테이너 로그 확인, 애플리케이션 오류 수정
OOMKilled메모리 부족으로 종료메모리 제한 증가 또는 메모리 누수 수정
Pending스케줄링 대기 중노드 리소스 및 노드 선택자 확인
CreateContainerConfigError컨테이너 설정 오류ConfigMap, Secret 참조 확인

진단 방법:

  1. Pod 이벤트 확인

    • MCM 콘솔에서 Pod 상세 페이지의 "이벤트" 탭 확인

  2. 컨테이너 로그 확인

    # Pod 로그 확인
    kubectl logs <pod-name> -n <namespace>

    # 이전 컨테이너 로그 확인 (CrashLoopBackOff의 경우)
    kubectl logs <pod-name> -n <namespace> --previous

Deployment 복제본 불일치​

증상:

  • 원하는 복제본 수와 실제 복제본 수가 다름
  • 일부 클러스터에서만 복제본이 생성됨

원인:

  • 노드 리소스 부족
  • 스케줄링 제약 조건
  • 복제본 스케줄링 전략 문제

해결 방법:

  1. 노드 리소스 확인

    • Overview 페이지에서 클러스터별 리소스 사용량 확인
    • 노드 상세 페이지에서 할당 가능 리소스 확인

  2. 스케줄링 전략 확인

    • PropagationPolicy의 replicaScheduling 설정 확인
    • Duplicated vs Divided 전략 검토

  3. 이벤트 확인

    • Deployment 상세 페이지의 이벤트 탭 확인
    • 스케줄링 관련 오류 메시지 확인

UI 및 화면 문제​

페이지가 로드되지 않음​

증상:

  • 빈 화면 또는 로딩 상태가 지속됨
  • 오류 페이지 표시
  • 일부 컴포넌트만 표시됨

해결 방법:

  1. 페이지 새로고침

    • F5 또는 Ctrl/Cmd + R로 새로고침
    • 강력 새로고침: Ctrl/Cmd + Shift + R

  2. 브라우저 캐시 삭제

    • 브라우저 설정에서 캐시 및 쿠키 삭제
    • 사이트 데이터만 삭제하여 다른 사이트에 영향 없이 처리

  3. 브라우저 콘솔 확인

    • F12로 개발자 도구 열기
    • Console 탭에서 오류 메시지 확인

  4. 다른 브라우저로 시도

    • Chrome, Firefox, Edge 등 다른 브라우저에서 테스트

테마가 적용되지 않음​

증상:

  • 다크 모드 선택 후에도 라이트 모드로 표시
  • 테마가 부분적으로만 적용됨
  • 시스템 테마 연동이 작동하지 않음

해결 방법:

  1. 설정 다시 적용

    • Settings 페이지에서 테마를 다른 값으로 변경 후 다시 원하는 테마 선택

  2. 로컬 스토리지 확인

    • 브라우저 개발자 도구 → Application → Local Storage
    • MCM 관련 데이터가 저장되어 있는지 확인

  3. 페이지 새로고침

    • 강력 새로고침으로 캐시된 스타일 새로 로드

토폴로지가 느리거나 멈춤​

증상:

  • 토폴로지 맵 로딩이 오래 걸림
  • 드래그, 줌 등의 조작이 느림
  • 브라우저가 응답하지 않음

원인:

  • 표시되는 노드 수가 너무 많음
  • 브라우저 메모리 부족
  • 하드웨어 가속 비활성화

해결 방법:

  1. 노드 수 제한 조정

    • Settings → 토폴로지 → 리소스 유형별 최대 노드 수를 낮은 값(5~10)으로 조정

  2. 필터 사용

    • 특정 네임스페이스 또는 클러스터만 선택
    • 필요한 리소스 유형만 표시

  3. 브라우저 하드웨어 가속 활성화

    • 브라우저 설정에서 "하드웨어 가속 사용" 옵션 활성화

  4. 다른 탭/프로그램 닫기

    • 시스템 리소스 확보를 위해 불필요한 프로그램 종료

검색이 작동하지 않음​

증상:

  • 검색어 입력 후 결과가 표시되지 않음
  • 검색창에 포커스가 되지 않음
  • / 단축키가 작동하지 않음

해결 방법:

  1. 포커스 확인

    • 다른 입력 필드에 포커스가 있으면 단축키가 작동하지 않음
    • 입력 필드 밖을 클릭 후 / 키 시도

  2. 브라우저 확장 프로그램 확인

    • 일부 확장 프로그램이 키보드 단축키를 가로챌 수 있음
    • 시크릿 모드에서 테스트

  3. 직접 검색창 클릭

    • 상단 네비게이션의 검색 아이콘 직접 클릭

API 오류​

401 Unauthorized​

증상:

  • "인증되지 않았습니다" 오류
  • 모든 API 요청 실패
  • 빨간색 오류 알림 표시

해결 방법:

  1. 로그아웃 후 다시 로그인
  2. 토큰 재발급 후 새로 로그인
  3. 브라우저 로컬 스토리지 삭제 후 재시도

403 Forbidden​

증상:

  • "권한이 없습니다" 오류
  • 특정 리소스에만 접근 불가

해결 방법:

  1. 권한 확인

    • 사용 중인 토큰의 ClusterRole/Role 확인
    • 필요한 리소스에 대한 권한 부여

  2. 관리자에게 문의

    • RBAC 설정 변경 요청

500 Internal Server Error​

증상:

  • 서버 오류 메시지 표시
  • 특정 작업 수행 시 오류

해결 방법:

  1. 재시도

    • 일시적인 오류일 수 있으므로 잠시 후 재시도

  2. API 서버 상태 확인

    # Karmada API 서버 상태 확인
    kubectl -n karmada-system get pods -l app=karmada-apiserver
    kubectl -n karmada-system logs -l app=karmada-apiserver --tail=50

  3. 관리자에게 문의

    • 서버 로그 확인 필요

네트워크 오류​

증상:

  • "네트워크 오류" 또는 "연결 실패" 메시지
  • 간헐적인 연결 끊김

해결 방법:

  1. 네트워크 상태 확인

    • 인터넷 연결 상태 확인
    • VPN 연결 상태 확인

  2. 서버 접근성 확인

    # MCM API 서버 접근 테스트
    curl -k https://<mcm-api-server>/healthz

  3. 방화벽/프록시 확인

    • 필요한 포트가 열려 있는지 확인
    • 프록시 설정 확인

데이터 및 표시 문제​

오래된 데이터 표시​

증상:

  • 방금 생성한 리소스가 보이지 않음
  • 삭제한 리소스가 계속 표시됨
  • 상태가 업데이트되지 않음

해결 방법:

  1. 새로고침

    • 페이지 새로고침 버튼 클릭
    • 브라우저 새로고침

  2. 캐시 확인

    • API 응답이 캐시되었을 수 있음
    • 강력 새로고침 시도

숫자/통계 불일치​

증상:

  • Overview 통계와 실제 리소스 수가 다름
  • 클러스터별 합계가 맞지 않음

원인:

  • 데이터 동기화 지연
  • 일부 클러스터 연결 문제
  • 필터가 적용된 상태

해결 방법:

  1. 필터 상태 확인

    • 네임스페이스, 클러스터 필터가 적용되어 있는지 확인
    • 모든 필터 해제 후 확인

  2. 클러스터 상태 확인

    • 모든 클러스터가 Ready 상태인지 확인
    • NotReady 클러스터는 데이터가 정확하지 않을 수 있음

  3. 페이지 새로고침

    • 최신 데이터로 업데이트

리소스 생성/편집 문제​

Dialog에서 생성 버튼 비활성화​

증상:

  • 모든 필드를 입력했는데 생성 버튼이 비활성화됨
  • 필수 필드 표시가 없는데 생성 불가

원인:

  • 필수 필드 누락
  • 유효성 검증 실패
  • 중복된 이름

해결 방법:

  1. 모든 필드 확인

    • 네임스페이스 선택 확인
    • 정책 이름 입력 확인
    • 대상 리소스 선택 확인
    • 대상 클러스터 선택 확인

  2. 이름 중복 확인

    • 같은 이름의 정책이 이미 존재하는지 확인

  3. 입력 형식 확인

    • 이름은 소문자, 숫자, 하이픈만 사용 가능
    • 특수 문자 사용 불가

YAML 편집 오류​

증상:

  • YAML 저장 시 오류 발생
  • "유효하지 않은 YAML" 메시지

해결 방법:

  1. YAML 문법 확인

    • 들여쓰기가 올바른지 확인 (스페이스 2칸 또는 4칸 일관 사용)
    • 탭 대신 스페이스 사용

  2. 필수 필드 확인

    • apiVersion, kind, metadata 등 필수 필드 존재 확인

  3. YAML 검증

    • 온라인 YAML 검증 도구 사용
    • kubectl apply --dry-run=client 로 로컬 검증

브라우저 호환성​

지원 브라우저​

브라우저최소 버전상태
Google Chrome90+완전 지원
Microsoft Edge90+완전 지원
Firefox88+완전 지원
Safari14+완전 지원
Internet Explorer-지원 안 함

브라우저 관련 문제​

증상:

  • 특정 브라우저에서만 문제 발생
  • 레이아웃이 깨져 보임
  • 기능이 작동하지 않음

해결 방법:

  1. 브라우저 업데이트

    • 최신 버전으로 업데이트

  2. 확장 프로그램 비활성화

    • 광고 차단, 보안 관련 확장 프로그램 일시 비활성화

  3. 다른 브라우저 사용

    • Chrome을 권장

진단 정보 수집​

문제 해결을 위해 관리자에게 문의할 때 다음 정보를 제공하면 도움이 됩니다:

기본 정보​

  1. MCM 콘솔 버전

    • Settings 페이지 → 제품정보 섹션에서 확인

  2. 브라우저 정보

    • 브라우저 종류 및 버전
    • 운영체제

  3. 오류 메시지

    • 정확한 오류 메시지 텍스트
    • 오류 발생 시점 및 상황

브라우저 콘솔 로그​

  1. F12로 개발자 도구 열기
  2. Console 탭 선택
  3. 오류(빨간색) 및 경고(노란색) 메시지 캡처
  4. Network 탭에서 실패한 요청 확인

스크린샷​

  1. 오류 화면 캡처
  2. 오류 발생 전후 상황 설명

관련 문서​