본문으로 건너뛰기

서비스 관리

경로: /services, /services/edit/:id

서비스 관리는 KIOPS의 핵심 페이지입니다. Git 저장소 소스 코드를 컨테이너 이미지로 빌드하고, Kubernetes·Docker 환경에 배포하며, 보안 취약점까지 한 곳에서 관리합니다.

서비스 관리 화면

설치형 Basic 화면 — [빌드/배포] 원클릭 버튼과 목록 검색·필터가 없습니다
설치형 Basic 화면

권한 안내 — 일부 기능에 접근할 수 없다면 기관 관리자에게 권한을 요청하세요. 권한 설정은 [권한 관리] 페이지에서 확인합니다.

무엇을 하는 곳인가​

  • Git 저장소 연동: GitLab 저장소를 토큰으로 연결하고 브랜치·태그를 선택합니다. 커밋·브랜치 조회 같은 기본 읽기에는 최소 read_repository 스코프가 필요합니다. Webhook 등록과 이미지 Push까지 하려면 read_api·write_repository·write_registry 스코프가 모두 있어야 하고, 토큰 계정은 해당 프로젝트에서 Maintainer 이상이어야 합니다. 토큰은 GitLab → Settings → Access Tokens에서 발급합니다.
  • 빌드: BuildKit으로 Dockerfile을 컨테이너 이미지로 빌드합니다(빌더는 BuildKit 단일화). 실시간 로그·빌드 이력 제공.
  • 배포: 빌드 이미지를 Kubernetes(Deployment/Service 등) 또는 Docker 호스트에 배포하고, 롤백·배포 이력을 관리합니다.
  • 보안 분석: SAST(Semgrep+OpenGrep)·SCA(Trivy+Dependency-Check)·SBOM(CycloneDX)·DAST(ZAP+Nuclei)와 IaC(Checkov)·시크릿(Gitleaks)·보안 게이트(OPA, 8영역 종합 배포 판정)를 실행합니다. 모든 스캔은 보안 분석 페이지에서 실행·확인합니다([2026-05-27] 파이프라인 단계 탭의 하위 분석 탭이 이관됨).
  • 운영: 배포된 서비스에 로그 조회·재시작·리소스 모니터링·명령 실행 등 실시간 작업을 수행합니다.
  • 실행 이력: 파이프라인 실행 기록 전체를 조회합니다.

핵심 요소​

서비스 목록​

등록 서비스를 GitLab 프로젝트 단위 카드 그룹으로 묶어 표시합니다. 각 카드에는 서비스 이름, Git 저장소/기본 브랜치, 빌드·배포 상태, 취약점 요약(Critical/High/Medium/Low)이 보이며, 카드 헤더에 빌드·배포·설정·삭제 아이콘 버튼이 있습니다. 상태 배지 의미는 상태 사전을 참고하세요.

서비스 상세 탭​

서비스를 클릭하면 소스 유형에 따라 탭 구성이 달라집니다.

  • GitLab 연동: 소스 / 빌드 / 배포 / 운영 / 실행 이력 5개 탭

  • Docker Hub 이미지 기반: 이미지 / 배포 / 운영 / 실행 이력 4개 탭 (소스·빌드 없음)

  • 소스(GitLab): 하위 탭 없이 저장소 통계를 단일 화면에 표시합니다. 저장소 연결 상태, 브랜치 목록, 최근 커밋, 기여자(최근 90일 기준 커밋 수 상위 5명, services.branch 기준), 언어 비율, 태그, 배포된 버전(헤더의 커밋 SHA·이미지 태그), 최근 머지된 MR/PR 5건이 들어갑니다. 연결 테스트 버튼으로 빌드 전에 GitLab 토큰이 유효한지 확인할 수 있습니다. SAST 결과는 보안 분석으로 이관([2026-05-27]).

  • 이미지(Docker Hub): 사용할 이미지·태그 선택.

  • 빌드(GitLab): 빌드 설정·로그·이력. SCA 결과는 보안 분석으로 이관([2026-05-27]).

  • 배포: 배포 환경 설정·실행·이력.

  • 운영: 운영 모달 호출. K8s = 개요 / 파드 목록 / 워크로드 / 리소스 / 설정·시크릿 / 로그 / 명령 실행 / 도메인 설정(스케일링·HPA·재시작은 워크로드 탭). Docker·Podman = 개요 / 컨테이너 목록 / 로그 / 명령 실행 / 도메인 설정.

  • 실행 이력: 파이프라인 실행 기록 조회.

소스 탭

빌드 탭

배포 탭

실행 이력 탭

자동 CI와 Webhook​

코드 변경 시 자동 빌드·배포를 설정합니다.

  • 트리거: 브랜치 푸시, 태그 생성, 특정 파일/경로 변경(여러 조건 조합 가능).
  • 여는 방법: 빌드 탭의 자동 CI 설정 버튼, 또는 서비스 카드 액션 메뉴. 별도 "설정" 탭은 없습니다. 모달 안의 Webhook 환경 관리 버튼을 클릭하면 환경별 설정 창이 열립니다.
  • Webhook 환경: 서비스마다 로컬·개발·스테이징·운영 4개 환경이 있습니다. Webhook URL은 기관 Base URL + 서비스 경로로 만들어집니다. Base URL이 설정돼 있지 않으면 "미설정"으로 표시되므로 기관 관리자에게 설정을 요청하세요. GitLab 요청은 환경별 고유 Secret Token으로 인증합니다. 토큰을 다시 만들면 기존 토큰이 즉시 무효화되므로 GitLab 설정도 함께 갱신해야 합니다. 상태 배지 값은 상태 사전을 참고하세요.

배포된 버전 추적​

현재 배포 중인 서비스의 코드·이미지 정보를 표시합니다([2026-05-22]).

  • 표시 위치: 대시보드 서비스 현황 테이블 "배포 버전" 컬럼, 보안 분석 헤더, 소스 탭 헤더, 실행 이력 목록.
  • 표시 정보: 이미지 태그(사용자 입력 버전 또는 자동 타임스탬프, 사용자 입력은 굵게), 배포 시점, 배포 커밋 SHA(첫 7자), 배포 이미지 URL.
  • 위험도 매칭: SAST 결과를 배포 커밋 기준으로 재계산. 스캔 커밋 ≠ 배포 커밋이면 "이전 커밋" 라벨, 배포 정보 없으면 "매칭 불가".

실행 이력 컬럼​

표시되는 항목은 실행 번호, 실행 단계(소스/SAST/빌드/SCA/배포/운영/DAST를 색상으로 구분), 이미지 태그, 상태, 트리거(수동·웹훅·예약), 실행 시간과 소요 시간, 브랜치, 커밋(첫 7자이며 웹훅으로 실행한 것이 아니면 '-', [2026-05-22]), 실행자입니다. 각 기록을 펼치면 단계별 타임라인(시작·종료·소요·상태)이 나오므로 병목 구간을 찾을 수 있습니다.

빌드/저장소 통계​

  • 빌드: 총 빌드 수, 빌드 성공률, 평균 빌드 시간, 최근 빌드 이력.
  • 저장소: 총 커밋 수, 활성 브랜치 수, 기여자(최근 90일 상위 5명), 최근 머지 MR/PR 5건, 분석 기준 브랜치(services.branch, 미설정 시 default_branch), 최근 커밋 이력.

사용 방법​

서비스 등록​

서비스 추가 → 서비스명·설명·저장소 URL 입력 → GitLab Personal Access Token 입력(스코프는 위 참조) → 인증 완료 후 기본 브랜치(보통 main/develop) 선택 → 저장.

빌드 설정·실행​

빌드 탭 → 빌드 설정에서 구성:

  • Dockerfile 경로(기본 ./Dockerfile), 빌드 경로(Docker 빌드 컨텍스트, 기본 . = 루트; Dockerfile의 COPY/ADD 접근 범위 결정, 모노레포는 하위 폴더 지정).
  • 빌드 인자: ARG 값을 key=value로 입력(예 NODE_ENV=production).
  • 버전(이전 "태그"): 의미 있는 라벨(예 v1.2.3)을 이미지 태그로 사용합니다. 비우면 타임스탬프(예 20260326-143000)가 자동 생성됩니다. 영문·숫자·.·-·_만 최대 128자([2026-05-27]).
  • 레지스트리: 이미지 저장소 선택(Harbor 등).

빌드 실행: 빌드 탭 → 빌드 시작 → 브랜치/태그·캐시 사용 여부 선택 → 실시간 로그 표시, 완료 시 성공/실패와 생성된 이미지 태그 확인.

배포​

배포 탭 → 대상 환경(Kubernetes/Docker) 선택 → 배포 → 옵션 설정(네임스페이스[K8s], 레플리카[가용성 위해 2개 이상 권장], CPU/메모리 요청·제한, 환경 변수) → 배포 실행.

보안 스캔·취약점 관리​

각 스캔은 보안 분석 페이지의 해당 영역 탭에서 실행합니다([2026-05-27] 일원화). 실행 시점은 SAST가 커밋·MR 전, SCA가 의존성 업데이트·빌드 전, DAST가 스테이징 배포 후를 권장합니다. SBOM(CycloneDX)은 별개의 독립 스캔이며, 이미지 SBOM은 이미지 SCA를 실행할 때 함께 요청됩니다. 소스 SBOM은 SBOM/라이선스 탭에서 실행합니다.

발견된 취약점은 심각도별 필터 후 상세(설명·CVE·영향 위치·권장 조치)를 확인하고 수정(재스캔으로 해결 확인)·무시(환경에서 악용 불가 시 VEX 기반)·계획(수정 계획 등록) 중 하나로 처리합니다.

보안 분석 화면

DAST 주의

DAST는 실제 애플리케이션에 공격을 시뮬레이션하므로 반드시 테스트 환경에서만 실행하세요. 프로덕션 실행 시 서비스 장애·데이터 손상이 발생할 수 있습니다.

운영 작업​

서비스 목록/상세의 운영 버튼으로 배포된 서비스를 실시간 관리합니다.

  • 로그 조회: 컨테이너/Pod를 선택하고 로그 조회로 최근 로그를 터미널 출력에 표시합니다(초기화로 화면을 비움). 실시간 추적(follow)이 필요하면 [명령 실행] 탭의 실시간 모드를 사용하세요.
  • 재시작: 대상 컨테이너/Pod 재시작. 일시 중단이 발생할 수 있어 무중단이 필요하면 레플리카 2개 이상 + 롤링 업데이트를 사용하세요.
  • 리소스 모니터링: CPU(지속 80% 이상 주의)·메모리(제한 근접 시 OOM 위험). 별도 설치 없이 수집됩니다.
  • 명령 실행: 컨테이너/Pod 대상 명령 실행. 대화형 셸(exec -it, attach, port-forward)은 미지원, 단발성·스트리밍 모드만 가능하며 동시 세션 수·출력 크기 제한. 모든 실행은 감사 로그에 기록됩니다.
  • 롤백: 운영 모달에는 롤백 버튼이 없습니다. 배포와 롤백은 [서비스 관리] 의 빌드·배포에서 수행합니다.
  • HPA·스케일링·재시작(K8s 전용): 워크로드 탭에서 관리합니다. HPA는 최소/최대 레플리카·CPU 임계값(targetCPU %)을 설정하며 단순 CPU 기반만 지원(메모리·커스텀·다중 메트릭, 스케일링 정책 미지원). HPA는 클러스터에 metrics-server가 설치되어 있어야 동작합니다.

데이터 보관 — Git 토큰은 암호화되어 저장되고, 빌드 로그는 일정 기간 후 자동 삭제됩니다. 중요한 로그는 미리 다운로드해 보관하세요.

관련 작업​