Skip to main content

자주 묻는 질문 (FAQ)

KIWI 플랫폼 사용 중 자주 발생하는 질문과 답변을 정리했습니다.

시작하기​

Q. KIWI를 처음 사용합니다. 어떻게 시작하나요?​

A. KIWI 시작은 다음 순서로 진행합니다:

  1. [장비 관리] 페이지에서 관리할 서버 등록
  2. [런타임 환경] 페이지에서 K8s 클러스터 또는 Docker 런타임 연결
  3. [서비스 관리] 페이지에서 Git 저장소 연동
  4. 빌드 및 배포 설정 완료

자세한 내용: 시스템 등록 시나리오

Q. 필요한 권한은 무엇인가요?​

A. KIWI는 다음과 같은 권한 체계를 사용합니다:

권한접근 가능 페이지설명
device[장비 관리]서버/장비 관리
infra[인프라 관리], [런타임 환경]K8s/Docker 환경 관리
service[서비스 관리]서비스 빌드/배포
backup[백업 관리]백업/복구
database[데이터베이스 관리]DB 관리
audit[감사 로그]로그 조회

권한 요청은 [권한 관리] 페이지에서 관리자에게 요청하세요.

장비 관리​

Q. 서버 연결 테스트가 실패합니다.​

A. 다음을 확인하세요:

  1. 네트워크 확인: 서버 IP가 접근 가능한지 확인
  2. SSH 포트 확인: 기본 포트(22) 외 다른 포트 사용 시 정확히 입력
  3. 방화벽 확인: SSH 포트가 방화벽에서 허용되어 있는지 확인
  4. 인증 정보 확인: 사용자명과 비밀번호/SSH 키 확인

관련 페이지: [장비 관리]

Q. 게이트웨이를 통해 접속해야 하는 서버는 어떻게 등록하나요?​

A. KIWI는 다중 홉 SSH를 지원합니다:

  1. [장비 관리] 페이지에서 게이트웨이 서버 먼저 등록
  2. 내부 서버 등록 시 "SSH 터널" 옵션 선택
  3. 게이트웨이 서버 선택 후 내부 서버 정보 입력

런타임 환경​

Q. 외부 Kubernetes 클러스터를 연결하려면 어떻게 하나요?​

A. 다음 단계를 따르세요:

  1. [런타임 환경] 페이지 이동
  2. "외부 런타임 가져오기" 버튼 클릭
  3. kubeconfig 파일 업로드 또는 직접 입력
  4. 연결 테스트 후 저장

주의사항: kubeconfig에 유효한 토큰이 포함되어 있어야 합니다.

자세한 내용: 시스템 등록 시나리오

Q. Docker 런타임이 연결되지 않습니다.​

A. 다음을 확인하세요:

  1. Docker 데몬 실행 확인: systemctl status docker
  2. 소켓 권한 확인: 사용자가 docker 그룹에 속해 있는지 확인
  3. 원격 API 설정: TCP 소켓 사용 시 /etc/docker/daemon.json 설정 확인

관련 페이지: [런타임 환경]

서비스 관리​

Q. Git 저장소 연결이 실패합니다.​

A. 다음을 확인하세요:

  1. URL 형식: HTTPS URL 사용 권장 (https://gitlab.com/...)
  2. 토큰 권한: Personal Access Token에 read_repository 권한 필요
  3. 토큰 만료: 토큰 유효기간 확인

관련 페이지: [서비스 관리]

Q. 빌드가 실패합니다. 어떻게 확인하나요?​

A. 빌드 실패 시 확인 순서:

  1. [서비스 관리] → 서비스 선택 → 빌드 탭
  2. 실패한 빌드의 로그 확인
  3. 일반적인 원인:
    • Dockerfile 문법 오류
    • 베이스 이미지 접근 불가
    • 의존성 설치 실패
    • 레지스트리 인증 실패

Q. 이미지 푸시가 실패합니다.​

A. 다음을 확인하세요:

  1. 레지스트리 URL: 정확한 레지스트리 주소 확인
  2. 인증 정보: 레지스트리 로그인 정보 확인
  3. 프로젝트 권한: 레지스트리 내 프로젝트에 푸시 권한 확인
  4. 이미지 태그: 올바른 태그 형식 사용

관련 페이지: [서비스 관리]

보안 스캔​

Q. SAST 스캔 결과가 나오지 않습니다.​

A. 다음을 확인하세요:

  1. 지원 언어: CodeQL/Semgrep이 지원하는 언어인지 확인
  2. 저장소 크기: 대용량 저장소의 경우 시간이 오래 걸릴 수 있음
  3. 소스 코드 위치: 소스 코드가 루트 디렉토리에 있는지 확인

관련 페이지: [서비스 관리] → 보안 탭

자세한 내용: 보안 스캔 설정 시나리오

Q. SCA 스캔에서 너무 많은 취약점이 나옵니다.​

A. VEX 필터를 활용하세요:

  1. [서비스 관리] → 서비스 선택 → 보안 탭
  2. SCA 결과에서 "VEX 필터" 활성화
  3. 실제로 영향받지 않는 취약점이 자동 필터링됨

또는 예외 정책을 설정하여 특정 취약점을 무시할 수 있습니다.

Q. SBOM은 어떻게 다운로드하나요?​

A. 다음 단계를 따르세요:

  1. [서비스 관리] → 서비스 선택 → 보안 탭
  2. "SBOM 생성" 버튼 클릭
  3. 소스 SBOM 또는 이미지 SBOM 선택
  4. CycloneDX 또는 SPDX 포맷으로 다운로드

자세한 내용: 보안 스캔 설정 시나리오

배포​

Q. 배포 후 Pod가 시작되지 않습니다.​

A. 다음을 확인하세요:

  1. 이미지 풀: 이미지가 정상적으로 풀되는지 확인
  2. 리소스 제한: CPU/메모리 제한이 너무 낮지 않은지 확인
  3. 환경 변수: 필수 환경 변수가 설정되어 있는지 확인
  4. 포트 설정: 컨테이너 포트가 올바르게 설정되어 있는지 확인

디버깅 방법:

kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

Q. 배포된 서비스에 접근이 안 됩니다.​

A. 다음을 확인하세요:

  1. Service 설정: ClusterIP/LoadBalancer/NodePort 확인
  2. Ingress 설정: Ingress 규칙 및 도메인 설정 확인
  3. 네트워크 정책: NetworkPolicy로 트래픽이 차단되지 않는지 확인

백업 관리​

Q. 백업은 어떻게 생성하나요?​

A. 다음 단계를 따르세요:

  1. [백업 관리] 페이지 이동
  2. "백업 생성" 버튼 클릭
  3. 백업 대상 선택 (etcd, 데이터베이스, PVC 등)
  4. 백업 저장소 선택 (로컬, MinIO, 외부 스토리지)
  5. 백업 실행

Q. 백업에서 복구하려면 어떻게 하나요?​

A. 다음 단계를 따르세요:

  1. [백업 관리] 페이지 이동
  2. 복구할 백업 선택
  3. "복구" 버튼 클릭
  4. 복구 대상 확인 후 실행

주의: 복구 작업은 기존 데이터를 덮어씁니다. 신중히 진행하세요.

권한 및 사용자​

Q. 새 사용자를 초대하려면 어떻게 하나요?​

A. Manager 이상 권한이 필요합니다:

  1. [사용자 관리] 페이지 이동
  2. "사용자 초대" 버튼 클릭
  3. 이메일 입력 및 역할 선택
  4. 초대 발송

Q. 사용자 권한을 변경하려면 어떻게 하나요?​

A. Manager 이상 권한이 필요합니다:

  1. [권한 관리] 페이지 이동
  2. 권한을 변경할 사용자 선택
  3. 필요한 권한 체크/해제
  4. 저장

문제 해결​

Q. 화면이 로딩 중에서 멈춥니다.​

A. 다음을 시도하세요:

  1. 브라우저 새로고침 (Ctrl+F5)
  2. 브라우저 캐시 삭제
  3. 다른 브라우저로 시도
  4. 네트워크 연결 확인

문제가 지속되면 관리자에게 문의하세요.

Q. 오류 메시지가 표시됩니다.​

A. 오류 메시지를 확인하고 다음을 참고하세요:

오류 유형원인해결 방법
401 Unauthorized로그인 만료다시 로그인
403 Forbidden권한 부족관리자에게 권한 요청
404 Not Found리소스 없음URL 및 리소스 존재 확인
500 Internal Error서버 오류관리자에게 문의

추가 도움말​

더 자세한 정보가 필요하면 다음 문서를 참고하세요:

시스템 설정​

빌드 및 배포​

운영 관리​

관리자 기능​