본문으로 건너뛰기

자주 묻는 질문 (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: [감사 로그] - 로그 조회

권한 부여는 관리자(PlatformAdmin/Manager, 그리고 자기 팀 한정으로 TeamManager)가 [사용자 관리] 페이지에서 수행합니다. 필요한 권한은 [대시보드] 의 권한 요청 카드에서 바로 요청할 수 있습니다. ([권한 관리] 페이지는 각 권한이 포함하는 접근 범위를 확인하는 읽기전용 참조 페이지입니다.)

메뉴가 아예 보이지 않는다면 권한 문제일 수도, 라이선스 문제일 수도 있습니다. 그 화면의 주소로 직접 들어가 404면 라이선스, "접근 권한이 없습니다" 차단 카드면 권한 문제입니다 — 플랜과 기능 범위를 확인하세요.

장비 관리​

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 탭에서 확인합니다. SCA 스캔에는 VEX Hub 필터가 항상 적용됩니다. 사용자가 끄거나 켤 수 없습니다.

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

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

A. SBOM은 별개의 독립 스캔입니다. 이미지 SBOM은 이미지 SCA를 실행하면 함께 요청되며, SBOM / 라이선스 탭에서 직접 실행할 수도 있습니다. 소스 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. 요청 목록에서 대상 사용자의 승인 또는 거절 클릭
  4. 승인 후 [팀 관리] 에서 팀에 배정합니다. 팀에 배정되지 않으면 권한이 있어도 목록이 비어 보입니다.

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

추가 도움말​

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

시스템 설정​

빌드 및 배포​

운영 관리​

관리자 기능​