본문으로 건너뛰기

시스템 등록

KIWI를 사용하기 위한 첫 번째 단계입니다. 회사에 구축된 서버, Kubernetes 클러스터, Docker 환경을 KIWI에 등록하면, 이후 모든 배포와 관리 작업을 웹 UI에서 간편하게 수행할 수 있습니다.

왜 시스템 등록이 필요한가요?​

시스템을 등록하면 다음과 같은 이점이 있습니다:

등록 전과 후 비교
  • 서버 접속: 등록 전에는 SSH 클라이언트로 직접 접속해야 하지만, 등록 후에는 웹 UI에서 원클릭으로 접속할 수 있습니다.
  • 컨테이너 배포: 등록 전에는 kubectl/docker 명령어를 수동으로 실행해야 하지만, 등록 후에는 버튼 클릭만으로 배포할 수 있습니다.
  • 상태 모니터링: 등록 전에는 서버별로 개별 확인해야 하지만, 등록 후에는 대시보드에서 한눈에 확인할 수 있습니다.
  • 백업 관리: 등록 전에는 스크립트 작성과 cron 설정이 필요하지만, 등록 후에는 스케줄 설정만으로 자동 백업됩니다.

사전 준비사항​

시스템 등록 전 다음 정보를 준비하세요:

  • 서버 정보: IP 주소, SSH 포트, 접속 계정 정보
  • Kubernetes 정보: kubeconfig 파일 (Master 노드의 ~/.kube/config)
  • Docker 정보: Docker가 설치된 서버 정보
권한 안내

이 기능에 접근할 수 없다면 기관 관리자에게 device, infra 권한을 요청하세요.

장비 관리 페이지

런타임 환경 페이지

서버(장비) 등록하기​

먼저 회사 서버를 KIWI에 등록합니다. 서버를 등록하면 SSH 접속, 상태 모니터링, Docker/Kubernetes 런타임 연결이 가능해집니다.

Step 1: 장비 등록 시작​

좌측 메뉴에서 **[장비 관리]**를 클릭하고, 우측 상단의 장비 등록 버튼을 클릭합니다.

Step 2: 장비 정보 입력​

등록할 서버의 정보를 입력합니다:

  • 장비명: 서버를 쉽게 식별할 수 있는 이름입니다. (예: production-server-01)
  • IP 주소: 서버의 IP 주소입니다. (예: 192.168.1.100)
  • SSH 포트: SSH 접속 포트입니다. (기본값: 22)
  • 위치 (선택): 데이터센터, 랙 위치 등을 입력합니다. (예: IDC-A, Rack-3)
  • VPN 프로파일 (선택): VPN을 통해 접속해야 하는 경우 선택합니다.

Step 3: SSH 인증 정보 입력​

서버에 접속하기 위한 인증 정보를 입력합니다:

  • 비밀번호 인증: 사용자명과 비밀번호로 인증합니다. 빠른 설정이 필요할 때 사용합니다.
  • SSH 키 인증 (권장): 개인 키 파일로 인증합니다. 보안이 중요한 환경에서 권장합니다.
SSH 키 인증 권장

보안을 위해 SSH 키 인증을 권장합니다. 비밀번호 인증은 무차별 대입 공격에 취약할 수 있습니다.

Step 4: 연결 테스트 및 저장​

연결 테스트 버튼을 클릭하여 연결을 확인합니다. "연결 성공" 메시지가 나타나면 저장 버튼을 클릭합니다.

연결 실패 시 확인사항
  • 서버의 방화벽에서 SSH 포트가 열려 있는지 확인
  • SSH 서비스가 실행 중인지 확인 (systemctl status sshd)
  • IP 주소와 포트가 정확한지 확인
  • 인증 정보(사용자명/비밀번호 또는 키)가 올바른지 확인

외부 Kubernetes 클러스터 등록​

기존에 구축된 Kubernetes 클러스터를 KIWI에 연결합니다. 연결하면 Pod 배포, 상태 모니터링, 로그 조회 등을 웹 UI에서 할 수 있습니다.

Step 1: 런타임 환경 페이지 이동​

좌측 메뉴에서 **[런타임 환경]**을 클릭하고, 외부 런타임 가져오기 버튼을 클릭합니다.

Step 2: 연결 방식 선택​

클러스터에 접근하는 방식을 선택합니다:

  • kubeconfig: kubeconfig 파일로 직접 연결합니다. 클러스터에 직접 접근 가능한 경우에 사용합니다.
  • SSH 터널: SSH를 통해 클러스터에 접근합니다. 방화벽 뒤에 있는 클러스터에 사용합니다.
  • VPN: VPN을 통해 클러스터에 접근합니다. VPN 연결이 필요한 환경에서 사용합니다.

Step 3: kubeconfig 업로드​

kubeconfig 파일을 드래그앤드롭하거나 파일 선택으로 업로드합니다.

kubeconfig 파일 위치

kubeconfig 파일은 보통 Kubernetes Master 노드의 ~/.kube/config에 있습니다. 이 파일을 복사하여 업로드하세요.

# Master 노드에서 실행
cat ~/.kube/config
kubeconfig 주의사항
  • kubeconfig에 포함된 인증 토큰이 만료되지 않았는지 확인하세요
  • 클러스터 관리자 권한이 포함된 kubeconfig 사용을 권장합니다 .
  • 민감한 정보이므로 안전하게 보관하세요

Step 4: 연결 확인 및 저장​

연결 테스트 버튼을 클릭합니다. 성공하면 클러스터 버전과 노드 정보가 표시됩니다. 저장을 클릭하여 등록을 완료합니다.

Docker 런타임 등록​

Docker가 설치된 서버를 KIWI 런타임으로 등록합니다. Kubernetes 없이 단일 서버에서 컨테이너를 운영할 때 사용합니다.

사전 준비

해당 서버가 **[장비 관리]**에 먼저 등록되어 있어야 합니다.

Step 1: 런타임 등록 시작​

좌측 메뉴에서 **[런타임 환경]**을 클릭하고, 런타임 등록 버튼을 클릭합니다.

Step 2: 런타임 유형 및 서버 선택​

런타임 유형으로 Docker 또는 Podman을 선택합니다. 장비 목록에서 해당 런타임이 설치된 서버를 선택합니다.

Docker vs Podman
  • Docker: 가장 널리 사용되는 컨테이너 런타임
  • Podman: Docker와 호환되며, 루트리스(rootless) 모드로 보안성이 높음

Step 3: Docker 소켓 경로 설정​

Docker 소켓 경로를 설정합니다:

  • 기본 소켓 (기본값: /var/run/docker.sock): 대부분의 경우에 사용합니다.
  • 원격 API (예: tcp://192.168.1.100:2375): TCP 소켓을 사용하는 경우에 설정합니다.

Step 4: 등록 완료 및 확인​

저장 버튼을 클릭합니다. 런타임 목록에서 컨테이너 목록이 정상적으로 조회되는지 확인하세요.

자주 묻는 질문​

SSH 연결이 실패합니다​

증상별 해결 방법:

  • "Connection refused": SSH 서비스가 중지되었습니다. systemctl start sshd 명령으로 서비스를 시작하세요.
  • "Connection timeout": 방화벽에서 차단되었습니다. 방화벽에서 SSH 포트를 허용하세요.
  • "Permission denied": 인증에 실패했습니다. 사용자명/비밀번호 또는 키를 확인하세요.

kubeconfig가 작동하지 않습니다​

  • 토큰 만료: kubeconfig 내 토큰이 만료되었을 수 있습니다. 새로운 kubeconfig를 발급받으세요.
  • 권한 부족: 클러스터 관리자 권한이 필요합니다.
  • 네트워크 문제: API 서버 주소에 접근 가능한지 확인하세요.

Docker 소켓 접근이 거부됩니다​

SSH 사용자가 docker 그룹에 포함되어 있어야 합니다:

# 서버에서 실행
sudo usermod -aG docker 사용자명

# 그룹 변경 적용을 위해 재로그인 필요

다음 단계​

시스템 등록이 완료되면 다음 작업을 진행하세요:

추천 다음 단계
  1. 서비스 등록 - Git 저장소를 연동하여 서비스를 등록합니다 .
  2. 보안 스캔 설정 - SAST/SCA 보안 스캔을 설정합니다 .
  3. 백업 설정 - 중요 데이터의 자동 백업을 설정합니다 .