본문으로 건너뛰기

장비 등록

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

이 가이드는 인프라/운영팀이 처음 KIOPS를 도입하면서 자신이 관리하는 서버들을 한 곳에 모으는 과정을 도와줍니다. 명령어를 외울 필요 없이, 모달에서 IP/포트/계정만 입력하면 KIOPS가 SSH 연결, 시스템 정보 수집, AWX 인벤토리 등록까지 자동으로 처리합니다.

장비 관리 페이지

시작하기 전에: 알아둘 용어​

처음 보는 용어들이 있어도 괜찮습니다. 이 가이드에서 자주 쓰이는 용어부터 짧게 정리합니다.

  • SSH: 원격 서버에 안전하게 명령을 보내는 통로입니다. (원격 터미널로 서버에 접속해 명령을 실행하는 방식)
  • 게이트웨이 / 점프 서버: 외부에서 내부 서버로 들어가기 위한 중간 관문 서버입니다. (내부 서버로 들어가기 전에 반드시 거쳐야 하는 중계 서버)
  • 멀티홉(다중 홉): 점프 서버 → 또 다른 서버 → 최종 서버처럼 여러 단계를 거쳐 연결하는 방식입니다.
  • 시스템 정보 수집: KIOPS가 SSH로 접속해 OS/CPU/메모리/디스크 정보를 자동으로 가져오는 동작입니다.
  • VPN: 외부 네트워크에서 내부망으로 들어가는 전용 터널입니다. (외부에서 사내망으로 들어가는 전용 터널)
  • 자격증명: SSH 비밀번호 또는 SSH 개인 키 파일입니다. 최초 입력 시 KIOPS 서버에 암호화(AES-256-GCM)되어 저장되고 이후 작업에서 자동으로 재사용됩니다. (브라우저에는 평문이 저장되지 않습니다.)

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

KIOPS는 SSH를 통해 서버에 접속하여 다양한 관리 작업을 수행합니다. 장비를 등록하면 서버 상태 모니터링(CPU·메모리·디스크), Docker/Podman 컨테이너 관리, 애플리케이션 배포·운영을 할 수 있습니다.

사전 요구사항​

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

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

SSH 접속 가능 여부가 확실치 않으면 등록 전에 터미널에서 미리 확인해 볼 수 있습니다(IT 담당자에게 요청해도 됩니다). 아래가 정상 접속되면 KIOPS에서도 연결됩니다.

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

등록 절차​

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

  1. 좌측 메뉴에서 [장비 관리] 페이지를 클릭합니다.
  2. 우측 상단의 장비 추가 버튼을 클릭합니다 (드롭다운이 아닌 단일 버튼).

장비 추가 모달 화면

Step 2: 기본 정보 입력​

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

  • 상위 장비 (선택): 점프 서버를 경유해야 하면 경유할 상위 장비를 선택하고, 직접 접속할 수 있으면 비워 둡니다(멀티홉, 용어 사전 참고). 상위 장비를 지정하면 모달 하단에 점프 서버에서 타겟으로 이어지는 SSH 홉 체인이 화살표로 표시되므로 경로를 확인할 수 있습니다.
  • 장비명: 장비를 구분할 식별명입니다(예: prod-web-01, dev-server). 환경(prod/dev)과 용도를 포함하면 나중에 찾기 쉽습니다.
  • IP 주소: SSH로 접속할 서버의 IP 주소입니다(예: 192.168.1.100). 상위 장비가 있으면 사설 IP를 입력합니다.
  • 접속 인증 정보 (포트별 계정): IP 주소를 입력하면 활성화되는 표입니다. 장비 모달에는 단일 포트 입력란이 없고, 이 표에서 포트별 계정을 등록합니다. 한 서버에 여러 포트(예: 22, 5501)와 포트별 계정을 둘 수 있고, 연결 배지는 마지막 접속 시도의 결과입니다 — 연결(성공) · 실패 · 미확인(아직 시도한 적 없음). 행의 [연결 확인] 으로 지금 확인할 수 있습니다. 보안상 SSH 포트를 바꾼 서버(예: 2222, 22022)는 이 표에 해당 포트로 계정을 추가하세요.
  • Nginx 서버로 사용 (선택): 이 장비를 외부 Nginx 전용 서버로 표시하는 체크박스입니다. 켜면 [서비스 관리 > 도메인 설정]의 외부 Nginx 연결에서 이 장비를 선택할 수 있어, 접속 정보를 다시 입력하지 않고 등록된 SSH 인증을 재사용합니다.

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

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

  • 위치: 서버의 물리적 위치입니다 (예: 서울 IDC, AWS ap-northeast-2).
  • 설명: 서버에 대한 설명을 자유롭게 입력합니다.

장비 폼에는 VPN 프로파일 필드가 없습니다. VPN은 폼에서 지정하지 않습니다. 작업을 시작하는 시점에 대상의 접속 경로를 판단해, 직접 접속과 VPN이 모두 가능할 때만 연결 방식 선택 모달이 열립니다. 경로가 하나뿐이면 자동으로 직접 연결됩니다. 자세한 동작은 VPN 설정 → 연결 방식을 참고하세요.

하드웨어 정보 (선택 - 추가 정보 토글)​

"추가 정보" 토글을 펼치면 OS와 하드웨어 사양(OS·CPU·메모리·디스크)을 수동으로 입력할 수 있습니다. 시스템 정보 수집을 실행하면 자동으로 채워지므로, 수동 입력은 미리 인벤토리를 관리하고 싶을 때만 사용합니다.

Step 4: 저장 및 연결 확인​

  1. 모든 정보를 입력한 후 추가 버튼을 클릭하여 장비를 등록합니다.

  2. 등록 후 장비 목록에서 해당 장비의 시스템 정보 수집 아이콘(동기화 아이콘)을 클릭합니다.

  3. 대상이 VPN에 커버되면 연결 방식 선택 모달이 표시되어 VPN / 직접 SSH 중 하나를 선택합니다. 접속 경로가 하나뿐이면 이 모달 없이 바로 직접 연결됩니다.

    연결 방식 선택 모달

    • VPN: VPN 경로를 사용합니다. 활성 세션이 있으면 점프 서버 홉을 건너뛰고 타겟에 바로 접속합니다.
    • 직접 SSH: 등록된 다중 홉을 그대로 사용합니다 (상위 장비가 있으면 해당 자격 증명도 필요).

  4. 저장된 SSH 자격증명이 있으면 KIOPS가 이를 자동으로 사용해 곧바로 수집을 시작합니다. 자격증명이 없거나 잘못된 경우에만 입력 화면이 나타나며, 인증 방식을 선택합니다:

    • 비밀번호: 사용자명과 비밀번호를 입력합니다.
    • SSH 키: 사용자명을 입력하고, SSH 개인 키 파일(.pem, .key)을 업로드합니다.

  5. 연결이 성공하면 OS, CPU, 메모리, 디스크 정보가 자동으로 수집됩니다.

입력한 SSH 자격증명은 KIOPS 서버에 암호화(AES-256-GCM)되어 저장되고, 이후 같은 대상에서 작업할 때 자동으로 재사용됩니다. 같은 기관에서 다른 PC나 브라우저로 로그인해도 그대로 적용되며, 브라우저 데이터를 삭제해도 유지됩니다. 저장된 인증을 바꾸려면 [장비 관리]의 해당 장비 편집 화면에서 다시 입력합니다. 또한 등록이 완료되면 KIOPS는 해당 장비를 AWX 인벤토리에 자동 등록하여 Ansible 기반 자동화에 바로 쓸 수 있습니다.

장비 삭제 시 영향 분석​

장비를 삭제하기 전, KIOPS는 해당 장비와 연결된 자원을 점검하고 "이 장비를 삭제하면 다음 항목들이 영향을 받습니다"라는 확인 창으로 영향 범위를 표시합니다.

  • 하위 장비: 이 장비를 상위(점프 서버)로 사용하는 장비입니다. 하위 장비가 있으면 삭제가 차단되며, 하위 장비를 먼저 삭제해야 합니다.
  • 삭제될 런타임 환경: 이 장비가 사라지면 상위 장비가 없어지는 런타임(K8s 노드, Docker 호스트 등)입니다. 다른 장비로 인프라가 살아남는 경우(예: 멀티노드 클러스터)는 삭제되지 않습니다.
  • 함께 삭제될 서비스: 위 인프라에 배포된 서비스로, 각 서비스의 보안 스캔 결과와 연결된 DB까지 함께 삭제됩니다.
영향받는 자원은 영구 삭제됩니다

확인 창의 "위 항목은 영구 삭제되며 되돌릴 수 없습니다" 경고를 반드시 확인하세요. 삭제 전에 목록을 검토하고, 필요하면 자원을 먼저 정리한 뒤 장비를 삭제합니다.

문제 해결​

자주 하는 실수​

  • 상위 장비를 비워둔 채 사설 IP만 입력: 외부에서 직접 접속이 불가능한 사설 IP 서버인데 상위 장비를 비워두면, KIOPS가 KIOPS 호스트 → 타겟으로 바로 연결을 시도해 실패합니다. 점프 서버를 거쳐야 하는 환경이면 상위 장비에 점프 서버를 지정하세요.
  • SSH 포트를 22로 가정: 보안상 포트를 바꾼 서버(예: 2222, 22022)에 기본값 22로 계정을 추가하면 연결이 거부됩니다. 계정 추가 시 서버 sshd_config에 설정된 포트를 정확히 입력하세요.

연결 실패 (Connection refused)​

SSH 연결 실패: Connection refused

서버가 SSH 연결을 거부하고 있다는 의미입니다. 직접 점검이 어렵다면 IT 담당자에게 아래 확인을 요청하세요.

  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

인증 정보가 올바르지 않다는 의미입니다. 서버 설정 확인이 필요하면 IT 담당자에게 요청해도 됩니다.

  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 로 확인합니다.
    • KIOPS는 RSA, Ed25519, ECDSA 키 형식을 지원합니다.

다음에 할 일​

장비 등록이 완료되었습니다. 다음 작업을 우선순위 순으로 권장합니다.

  1. 런타임 환경 등록 - 등록한 장비 위에 Kubernetes/Docker/Podman 런타임을 연결합니다 (가장 먼저).
  2. 시스템 정보 수집 재실행 - 하드웨어 사양이 누락되어 있다면 장비 목록에서 동기화 아이콘을 다시 실행해 OS/CPU/메모리/디스크를 채웁니다.
  3. VPN 설정 - 사외 네트워크에서 접근해야 한다면 VPN 프로파일을 등록해 두면 연결 방식 모달에서 바로 선택할 수 있습니다.

관련 가이드​