본문으로 건너뛰기

장비 등록

KIWI 플랫폼에서 관리할 서버를 등록하는 방법을 안내합니다. 장비 등록은 모든 것의 시작점입니다. 서버를 먼저 등록해야 그 위에 Docker나 Kubernetes 같은 런타임을 연결할 수 있습니다.

장비 관리 페이지

왜 장비 등록이 필요한가요?​

KIWI는 SSH를 통해 서버에 접속하여 다양한 관리 작업을 수행합니다. 장비를 등록하면 다음과 같은 일을 할 수 있습니다:

  • 서버 상태 모니터링 (CPU, 메모리, 디스크 사용량)
  • Docker/Podman 컨테이너 관리
  • 애플리케이션 배포 및 운영
SSH란?

SSH(Secure Shell)는 네트워크를 통해 원격 서버에 안전하게 접속할 수 있게 해주는 프로토콜입니다. 마치 서버 앞에 직접 앉아서 터미널을 사용하는 것처럼 원격으로 명령을 실행할 수 있습니다.

사전 요구사항​

장비를 등록하기 전에 다음 조건이 충족되어야 합니다:

  • 등록할 서버가 SSH 접속 가능해야 합니다 .
  • SSH 계정은 root 또는 sudo 권한이 필요합니다 .
  • KIWI 에이전트가 해당 서버에 접속할 수 있도록 네트워크 정책이 허용되어야 합니다 .
  • SSH 인증에 사용할 비밀번호 또는 SSH 개인 키 파일(.pem, .key)을 준비합니다 .
사전 확인 방법

터미널에서 다음 명령으로 서버 접속을 미리 테스트해 보세요:

# 비밀번호 인증
ssh 사용자명@서버IP주소

# SSH 키 인증
ssh -i /path/to/private_key 사용자명@서버IP주소

정상적으로 접속된다면 KIWI에서도 문제없이 연결할 수 있습니다.

등록 절차​

Step 1: 장비 관리 페이지 이동​

  1. 좌측 메뉴에서 [장비 관리] 페이지를 클릭합니다 .
  2. 우측 상단의 추가하기 드롭다운에서 장비 추가를 선택합니다 .

Step 2: 기본 정보 입력​

장비 등록 모달에서 다음 정보를 입력합니다:

  • 상위 장비 (선택): 점프 서버를 경유해야 하는 경우, 경유할 상위 장비를 선택합니다. 직접 접속 가능하면 비워둡니다.

  • 장비명: 장비를 구분할 수 있는 식별명입니다 .

    • 예: prod-web-01, dev-server
    • 나중에 쉽게 찾을 수 있도록 환경(prod/dev)과 용도를 포함하면 좋습니다 .

  • IP 주소: SSH로 접속할 서버의 IP 주소입니다 .

    • 예: 192.168.1.100
    • 상위 장비가 있으면 사설 IP를 입력하세요

  • 포트: SSH 접속 포트입니다 .

    • 기본값: 22
    • 보안을 위해 포트를 변경한 경우 해당 포트를 입력하세요

Step 3: 추가 정보 설정 (선택)​

필요에 따라 추가 정보를 입력할 수 있습니다:

  • 위치: 서버의 물리적 위치 정보입니다 (예: 서울 IDC, AWS ap-northeast-2)
  • VPN 프로파일: VPN을 통해 서버에 접속하는 경우 VPN 프로파일을 선택합니다 .
  • 설명: 서버에 대한 설명을 자유롭게 입력합니다 .
노트

추가 정보는 나중에 장비를 관리할 때 유용합니다. 장비가 많아지면 위치나 설명으로 원하는 서버를 빠르게 찾을 수 있습니다.

Step 4: 저장 및 연결 확인​

  1. 모든 정보를 입력한 후 추가 버튼을 클릭하여 장비를 등록합니다 .
  2. 등록 후 장비 목록에서 해당 장비의 시스템 정보 수집 아이콘(동기화 아이콘)을 클릭합니다 .
  3. SSH 자격증명 입력 모달이 나타나면 인증 방식을 선택합니다:
    • 비밀번호: 사용자명과 비밀번호를 입력합니다 .
    • SSH 키: 사용자명을 입력하고, SSH 개인 키 파일(.pem, .key)을 업로드합니다 .
  4. 연결이 성공하면 OS, CPU, 메모리, 디스크 정보가 자동으로 수집됩니다 .
SSH 자격증명 보관

입력한 SSH 자격증명(비밀번호, 개인 키)은 현재 사용 중인 브라우저에만 저장되며 서버로 전송되지 않습니다. 브라우저 데이터를 삭제하면 자격증명을 다시 입력해야 합니다.

시스템 정보 수집으로 연결 확인

장비 등록 후 시스템 정보 수집을 실행하면 SSH 연결이 정상인지 확인할 수 있습니다. 수집에 성공하면 장비 정보가 자동으로 채워집니다.

문제 해결​

연결 실패 (Connection refused)​

SSH 연결 실패: Connection refused

이 오류는 서버가 SSH 연결을 거부하고 있다는 의미입니다. 다음 사항을 확인해 주세요:

  1. 방화벽 설정 확인

    • 서버의 방화벽에서 SSH 포트(기본 22)가 허용되어 있는지 확인합니다 .
    • sudo ufw status 또는 sudo firewall-cmd --list-all로 확인 가능합니다 .

  2. SSH 서비스 상태 확인

    • SSH 서비스가 실행 중인지 확인합니다 .
    systemctl status sshd

  3. IP 주소와 포트 재확인

    • 입력한 IP 주소와 포트가 정확한지 다시 확인합니다 .
    • 특히 공인 IP와 사설 IP를 혼동하지 않았는지 확인하세요

인증 실패 (Permission denied)​

SSH 인증 실패: Permission denied

이 오류는 인증 정보가 올바르지 않다는 의미입니다. 다음 사항을 확인해 주세요:

  1. 계정 정보 확인

    • 입력한 사용자명과 비밀번호(또는 SSH 키)가 정확한지 확인합니다 .
    • 복사/붙여넣기 시 앞뒤에 공백이 포함되지 않았는지 확인하세요

  2. 비밀번호 인증 사용 시

    • 서버의 /etc/ssh/sshd_config에서 PasswordAuthentication이 yes로 설정되어 있는지 확인합니다 .
    grep PasswordAuthentication /etc/ssh/sshd_config

  3. SSH 키 인증 사용 시

    • 업로드한 개인 키가 PEM 형식인지 확인합니다 (파일 내용이 -----BEGIN ... PRIVATE KEY-----로 시작해야 합니다)
    • 서버의 ~/.ssh/authorized_keys에 해당 키의 공개 키가 등록되어 있는지 확인합니다 .
    • 서버의 /etc/ssh/sshd_config에서 PubkeyAuthentication이 yes로 설정되어 있는지 확인합니다 .
    grep PubkeyAuthentication /etc/ssh/sshd_config
    • KIWI는 RSA, Ed25519, ECDSA 키 형식을 지원합니다 .

다음 단계​

장비 등록이 완료되었습니다! 이제 등록한 장비에 런타임을 연결할 차례입니다: