본문으로 건너뛰기

자주 묻는 질문 (FAQ)

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

시작하기​

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

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

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

자세한 내용: 시스템 설정 시나리오

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

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

  • device: [장비 관리] - 서버/장비 관리
  • infra: [런타임 환경] - K8s/Docker 환경 관리
  • service: [서비스 관리] - 서비스 빌드/배포 (운영 모달 K8s/Docker/Podman 작업 포함)
  • security: [보안 분석] - SAST/SCA/DAST/SBOM/IaC/시크릿/게이트 스캔 권한 (기존 service 보유자도 폴백 노출)
  • backup: [백업 관리] - 백업/복구
  • database: [데이터베이스 관리] - DB 관리
  • vpn: [VPN 관리] - VPN 프로파일 관리
  • audit: [감사 로그] - 로그 조회

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

장비 관리​

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

A. 다음을 확인하세요:

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

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

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

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

  1. [장비 관리] 페이지에서 게이트웨이 서버 먼저 등록
  2. 내부 서버 등록 시 상위 장비로 게이트웨이 서버를 선택
  3. 내부 서버 정보(사설 IP, 포트) 입력

런타임 환경​

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

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

  1. [런타임 환경] 페이지 이동
  2. "런타임 환경 추가" 버튼 클릭 후 "기존 런타임 연결" 선택
  3. 환경 유형으로 external_kubernetes 선택 후 마스터 노드 SSH hops 입력 (또는 등록된 장비 선택)
  4. preflight 8항목(kubeadm/kubelet/cni 등) 자동 검증 후 등록

주의사항: kubeconfig 파일 업로드 방식은 사용하지 않으며, SSH 접근으로 클러스터 정보를 자동 감지합니다.

자세한 내용: 시스템 설정 시나리오

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

관련 페이지: [보안 분석] → 서비스 선택 → SAST 탭

자세한 내용: 보안 분석 가이드

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

A. SCA 결과는 [보안 분석] → 서비스 선택 → SCA 탭에서 확인합니다. KIOPS는 SCA 스캔 시 VEX Hub 필터링을 백엔드에서 디폴트로 활성화합니다.

  • 사용자가 토글로 VEX를 켜고 끌 수는 없으며, 영향 받지 않는 취약점은 자동 제외됩니다.
  • 결과 화면(CategorizedVulnerabilityView)에서 카테고리별로 보고, 각 취약점을 false_positive 또는 accepted_risk(위험 수용)로 분류해 노이즈를 줄일 수 있습니다.

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

A. SBOM은 SAST·SCA와 별개의 독립 스캔으로 생성합니다. SBOM / 라이선스 탭에서 직접 실행하세요.

  1. [보안 분석] → 서비스 선택 → SBOM / 라이선스 탭 이동
  2. 출처 토글에서 컨테이너 이미지(이미지 SBOM) 또는 소스코드(소스 SBOM)를 선택하고 **[스캔 시작]**을 클릭 (이미지 SBOM은 Syft, 소스 SBOM·라이선스는 Syft + ScanCode)
  3. 생성된 SBOM을 같은 탭에서 CycloneDX 1.5 (JSON) 형식으로 다운로드 (SPDX/XML 미지원)

자세한 내용: SBOM 생성 가이드

배포​

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. 백업 저장소 선택 (로컬, 오브젝트 스토리지(SeaweedFS 등))
  5. 백업 실행

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

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

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

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

권한 및 사용자​

Q. 새 사용자를 기관에 추가하려면 어떻게 하나요?​

A. 사용자가 회원가입 시 기관을 선택하면 가입 요청이 생성됩니다. PlatformAdmin 또는 Manager가 처리합니다.

  1. [사용자 관리] 페이지 이동
  2. 가입 승인 대기 탭 클릭
  3. 요청 목록에서 대상 사용자의 승인 또는 거절 클릭

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

A. PlatformAdmin 또는 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: 서버 오류 → 관리자에게 문의

추가 도움말​

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

시스템 설정​

빌드 및 배포​

운영 관리​

관리자 기능​