장비 등록

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

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

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

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

• SSH: 원격 서버에 안전하게 명령을 보내는 통로입니다. (서버 앞에 직접 앉아서 키보드 치는 느낌)
• 게이트웨이 / 점프 서버: 외부에서 내부 서버로 들어가기 위한 중간 관문 서버입니다. (아파트 경비실을 거쳐야 동에 들어가는 것과 비슷)
• 멀티홉(다중 hop): 점프 서버 → 또 다른 서버 → 최종 서버처럼 여러 단계를 거쳐 연결하는 방식입니다.
• 시스템 정보 수집: KIOPS가 SSH로 접속해 OS/CPU/메모리/디스크 정보를 자동으로 가져오는 동작입니다.
• VPN: 외부 네트워크에서 내부망으로 들어가는 전용 터널입니다. (회사 사내망에 접속할 때 켜는 그 VPN)
• 자격증명: SSH 비밀번호 또는 SSH 개인 키 파일입니다. 브라우저에만 저장되며 서버로 전송되지 않습니다.

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

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

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

SSH란?

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

사전 요구사항

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

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

사전 확인 방법

관리자에게 SSH 접속 가능 여부를 미리 확인 요청하세요. 직접 확인하려면 터미널에서 아래와 같이 시도해 볼 수 있습니다(IT 담당자에게 부탁해도 됩니다):

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

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

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

---

등록 절차

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

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

Step 2: 기본 정보 입력

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

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

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

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

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

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

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

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

상위 장비 선택 시 SSH 경로가 시각화됩니다

상위 장비를 지정하면 모달 하단에 점프 서버 → 타겟 서버로 이어지는 SSH hop 체인이 화살표로 표시됩니다. 다단계 경유가 필요한 환경에서 경로를 시각적으로 확인할 수 있습니다.

자주 하는 실수: 상위 장비를 비워둔 채 사설 IP 입력

외부에서 직접 접속이 불가능한 사설 IP 서버인데 상위 장비를 비워두고 사설 IP만 입력하면, KIOPS가 KIOPS 호스트 → 타겟으로 바로 연결을 시도해 실패합니다. 점프 서버를 거쳐야 하는 환경이라면 반드시 상위 장비에 점프 서버를 지정하세요.

자주 하는 실수: SSH 포트 22 가정

보안 강화를 위해 SSH 포트를 변경한 서버(예: 2222, 22022)는 기본값 22로 두면 연결이 거부됩니다. 서버의 sshd_config에 설정된 포트를 정확히 입력하세요.

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

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

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

장비 폼에는 VPN 프로파일 필드가 없습니다

KIOPS 0.x 이후 장비 등록 폼에서는 VPN 프로파일을 직접 지정하지 않습니다. 대신 작업을 시작하는 시점에 표시되는 연결 방식 선택 모달(ConnectionSelectionModal) 에서 자동 / VPN / 직접 SSH 중 하나를 선택해 해당 작업의 연결 경로를 결정합니다. 자세한 동작은 VPN 설정 → 연결 방식을 참고하세요.

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

"추가 정보" 토글을 펼치면 OS와 하드웨어 사양을 수동으로 입력할 수 있습니다. 시스템 정보 수집을 실행하면 이 항목들은 자동으로 채워지므로, 수동 입력은 미리 인벤토리를 관리하고 싶은 경우에만 사용합니다.

• OS: 운영체제 (예: Ubuntu 22.04, RHEL 8)
• CPU: CPU 정보 (예: Intel Xeon, 8 cores)
• 메모리: 메모리 용량 (예: 16 GB)
• 디스크: 디스크 용량 (예: 500 GB)

Step 4: 저장 및 연결 확인

1. 모든 정보를 입력한 후 추가 버튼을 클릭하여 장비를 등록합니다.
2. 등록 후 장비 목록에서 해당 장비의 시스템 정보 수집 아이콘(동기화 아이콘)을 클릭합니다.
3. 연결 방식 선택 모달이 표시되면 자동 / VPN / 직접 SSH 중 하나를 선택합니다.

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

4. SSH 자격증명 입력 모달에서 인증 방식을 선택합니다:
   • 비밀번호: 사용자명과 비밀번호를 입력합니다.
   • SSH 키: 사용자명을 입력하고, SSH 개인 키 파일(.pem, .key)을 업로드합니다.
5. 연결이 성공하면 OS, CPU, 메모리, 디스크 정보가 자동으로 수집됩니다.

SSH 자격증명 보관

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

자주 하는 실수: 자격증명을 다른 PC에서도 쓸 수 있다고 가정

자격증명은 KIOPS 서버에 저장되지 않고 로그인한 브라우저(localStorage) 에만 저장됩니다. 다른 PC/브라우저에서 같은 사용자로 로그인해도 자격증명은 따라가지 않으므로, 새 환경에서는 다시 입력해야 합니다.

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

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

AWX 호스트 자동 등록

장비 등록이 완료되면 KIOPS는 해당 장비를 AWX 인벤토리에 자동으로 등록합니다. 별도 작업 없이 Ansible 기반 자동화 작업에 즉시 사용할 수 있습니다.

---

장비 삭제 시 영향 분석

장비를 삭제하기 전, KIOPS는 해당 장비와 연결된 자원을 점검하고 영향 범위를 표시합니다.

• 하위 장비: 이 장비를 상위(점프 서버)로 사용하는 장비 목록
• 연결된 서비스: 해당 장비의 런타임에 배포된 서비스 목록
• orphan 인프라: 장비 삭제 시 부모를 잃게 되는 런타임(K8s 노드, Docker 호스트 등)

위 자원이 존재하면 먼저 정리한 뒤 장비를 삭제하는 것을 권장합니다.

---

문제 해결

연결 실패 (Connection refused)

SSH 연결 실패: Connection refused

이 오류는 서버가 SSH 연결을 거부하고 있다는 의미입니다. 직접 점검이 어렵다면 DB 관리자 또는 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

이 오류는 인증 정보가 올바르지 않다는 의미입니다. 서버 설정 확인이 필요한 항목은 DB 관리자 또는 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 프로파일을 등록해 두면 연결 방식 모달에서 바로 선택할 수 있습니다.

관련 가이드

• Kubernetes 연결 - 등록한 장비에 K8s 클러스터 연결하기
• Docker 연결 - 등록한 장비에 Docker 런타임 연결하기