Skip to main content

Device Registration

This guide explains how to register a server for management in the KIOPS platform. Device registration is the starting point for everything. You must register a server first before you can connect runtimes like Docker or Kubernetes on top of it.

This guide helps infrastructure and operations teams getting started with KIOPS bring every server they manage into one place. There is no need to memorize commands; once you fill in the IP, port, and account in the modal, KIOPS handles SSH connection, system info collection, and AWX inventory registration for you.

Device Management

Before You Start: Terms to Know​

It is fine if some of the terms below are new. Here is a short primer on the words used most often in this guide.

  • SSH: A secure tunnel for sending commands to a remote server (it feels like sitting in front of the server's keyboard).
  • Gateway / Jump server: An intermediate server you must pass through to reach internal hosts (think of the lobby guard you greet before entering a building).
  • Multi-hop: Connecting through several stages, such as jump server -> another server -> final target.
  • System info collection: KIOPS's action that SSHes into a host and automatically gathers OS, CPU, memory, and disk facts.
  • VPN: A dedicated tunnel into an internal network (the same VPN you turn on to reach your office intranet).
  • Credentials: Either an SSH password or an SSH private key file. They are kept only in your browser and never sent to the server.

Why Is Device Registration Needed?​

KIOPS connects to servers via SSH to perform various management tasks. Once you register a device, you can:

  • Monitor server status (CPU, memory, disk usage)
  • Manage Docker/Podman containers
  • Deploy and operate applications.
What is SSH?

SSH (Secure Shell) is a protocol that allows you to securely connect to remote servers over a network. It lets you execute commands remotely as if you were sitting directly in front of the server's terminal.

Prerequisites​

The following conditions must be met before registering a device:

  • The server to register must be accessible via SSH
  • The SSH account must have root or sudo permissions
  • Network policy must allow the KIOPS agent to access that server.
  • Prepare a password or SSH private key file (.pem, .key) for SSH authentication.
Pre-check Method

Ask your administrator to confirm SSH access is available. If you want to verify it yourself, you can try the following from a terminal (you can also ask your IT contact to run it):

# Password authentication
ssh username@server-ip-address

# SSH key authentication
ssh -i /path/to/private_key username@server-ip-address

If you connect successfully, KIOPS will be able to connect without problems too.

Registration Procedure​

Step 1: Navigate to Device Management Page​

  1. Click the [Device Management] page in the left menu.
  2. Click the Add Device button in the upper right corner (it is a single button, not a dropdown).

Add Device modal

Step 2: Enter Basic Information​

Enter the following information in the device registration modal:

  • Parent Device (Optional): Select the parent device (jump server) if routing through one (multi-hop, see glossary). Leave empty if directly accessible.

  • Device Name: An identifier to distinguish the device.

    • Example: prod-web-01, dev-server
    • Including environment (prod/dev) and purpose makes it easier to find later.

  • IP Address: The server's IP address for SSH access.

    • Example: 192.168.1.100
    • Enter private IP if using a parent device.

  • Port: The SSH access port

    • Default: 22
    • Enter the appropriate port if you've changed it for security.
Selecting a parent device visualizes the SSH path

When you choose a parent device, the modal displays the SSH hop chain from the jump server to the target as an arrow path at the bottom. This helps you visually verify multi-hop routes.

Common pitfall: leaving parent device empty while using a private IP

If a server is only reachable through a jump host but you leave Parent Device empty and enter only a private IP, KIOPS will try to connect directly from the KIOPS host to the target and fail. For environments that require a jump server, always set the Parent Device to that jump host.

Common pitfall: assuming SSH port 22

Servers hardened with a non-default SSH port (for example 2222 or 22022) will refuse the connection if you leave the default 22. Enter the exact port configured in the server's sshd_config.

Step 3: Configure Additional Information (Optional)​

You can enter additional information as needed:

  • Location: Physical location of the server (e.g., Seoul IDC, AWS ap-northeast-2)
  • Description: Enter a description for the server freely.
The device form does not contain a VPN profile field

Since KIOPS 0.x, the device registration form no longer takes a VPN profile. Instead, the Connection Selection Modal (ConnectionSelectionModal) that appears when starting an operation lets you choose Auto / VPN / Direct SSH per task. See VPN Settings → Connection Mode for details.

Hardware Information (Optional - Additional Info toggle)​

Expanding the "Additional Info" toggle lets you manually enter the OS and hardware specs. These fields are auto-populated when system info collection runs, so use manual input only when you want to seed the inventory ahead of time.

  • OS: Operating system (e.g., Ubuntu 22.04, RHEL 8)
  • CPU: CPU information (e.g., Intel Xeon, 8 cores)
  • Memory: Memory capacity (e.g., 16 GB)
  • Disk: Disk capacity (e.g., 500 GB)

Step 4: Save and Verify Connection​

  1. After entering all information, click the Add button to register the device.
  2. In the device list, click the Collect System Info icon (sync icon) for the registered device.
  3. When the Connection Selection Modal appears, choose Auto / VPN / Direct SSH.

Connection selection modal

  • Auto: If an active VPN session exists for the device, the jump-server hop is skipped and the target is reached directly.
  • VPN: Explicitly use the VPN path.
  • Direct SSH: Use the registered multi-hop chain as-is (parent device credentials are required when one is configured).
  1. In the SSH credentials modal, select the authentication method:
    • Password: Enter the username and password
    • SSH Key: Enter the username and upload an SSH private key file (.pem, .key)
  2. If the connection succeeds, OS, CPU, memory, and disk information will be automatically collected.
SSH Credential Storage

SSH credentials (passwords, private keys) are stored only in your current browser and are never sent to the server. If you clear your browser data, you will need to re-enter your credentials.

Common pitfall: assuming credentials follow your account

Credentials are not stored on the KIOPS server; they live only in the browser localStorage where you typed them. Signing in as the same user from a different PC or browser will not carry the credentials over, so you must re-enter them on that machine.

Verify Connection via System Info Collection

After registering a device, running system info collection confirms that the SSH connection is working properly. On success, device information is automatically populated.

Automatic AWX Host Registration

Once device registration completes, KIOPS automatically registers the device in the AWX inventory. It is ready for Ansible-based automation tasks without any extra step.

Impact Analysis Before Deletion​

Before deleting a device, KIOPS inspects related resources and shows the impact scope:

  • Child devices: Devices that use this device as their parent (jump server)
  • Connected services: Services deployed on runtimes belonging to this device
  • Orphan infrastructure: Runtimes (K8s nodes, Docker hosts, etc.) that would lose their parent when the device is removed

If any of these exist, clean them up first before deleting the device.

Troubleshooting​

Connection Failure (Connection refused)​

SSH connection failed: Connection refused

This error means the server is refusing SSH connections. If you cannot inspect the server yourself, ask the DB administrator or your IT contact to verify the items below.

  1. Check Firewall Settings

    • Verify that the SSH port (default 22) is allowed in the server's firewall
    • You can check with sudo ufw status or sudo firewall-cmd --list-all

  2. Check SSH Service Status

    • Verify that the SSH service is running.
    systemctl status sshd

  3. Re-verify IP Address and Port

    • Double-check that the IP address and port entered are correct
    • Make sure you haven't confused public and private IP addresses.

Authentication Failure (Permission denied)​

SSH authentication failed: Permission denied

This error means the authentication information is incorrect. Server-side configuration checks can also be requested from the DB administrator or your IT contact.

  1. Verify Account Information

    • Verify that the username and password (or SSH key) entered are correct
    • Check that there are no leading or trailing spaces when copying/pasting.

  2. When Using Password Authentication

    • Verify that PasswordAuthentication is set to yes in the server's /etc/ssh/sshd_config
    grep PasswordAuthentication /etc/ssh/sshd_config

  3. When Using SSH Key Authentication

    • Verify the uploaded private key is in PEM format (file content should start with -----BEGIN ... PRIVATE KEY-----)
    • Verify the corresponding public key is registered in the server's ~/.ssh/authorized_keys
    • Verify that PubkeyAuthentication is set to yes in the server's /etc/ssh/sshd_config
    grep PubkeyAuthentication /etc/ssh/sshd_config
    • KIOPS supports RSA, Ed25519, and ECDSA key formats.

What to Do Next​

Device registration is complete. We recommend tackling the following items in order.

  1. Register a runtime environment - Attach a Kubernetes/Docker/Podman runtime on top of the device you just added (do this first).
  2. Re-run system info collection - If hardware fields are still blank, click the sync icon in the device list again to populate OS, CPU, memory, and disk.
  3. Configure VPN - If you need to reach the device from outside the corporate network, register a VPN profile so you can pick it directly from the connection selection modal.