> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xloud.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Hosts

> Build your cluster inventory, configure SSH access, and manage target nodes

## Overview

Hosts is where you build your cluster inventory --- the list of servers that form your cloud. Define which servers exist, their IP addresses, assign roles (controller, compute, storage), and set up SSH for remote configuration. Every server that participates in your cloud must be registered here before deployment can proceed.

<Note>
  **Prerequisites**

  * Bootstrap completed on the deployment server
  * IP addresses of all target servers
  * SSH credentials (username and password) for all target servers
  * Network connectivity between the deployment node and every target server
</Note>

***

## Deployment Modes

<CardGroup cols={2}>
  <Card title="All-in-One (AIO)" icon="server" color="#197560">
    Everything on **one server**. For labs, demos, and testing environments. XDeploy auto-detects the local hostname and IP address, then assigns all roles to localhost. No SSH configuration is required --- the deployment node is also the target.
  </Card>

  <Card title="Multi-Node Cluster" icon="network" color="#197560">
    Production setup with **separate servers** for different roles. Supports high availability, horizontal scaling, and workload isolation. Each server is assigned one or more roles and connected via SSH for remote configuration management.
  </Card>
</CardGroup>

***

## Node Roles

Every server in your cluster is assigned one or more roles that determine which services run on it. The following table describes each role and the services it hosts.

| Role                | Purpose               | Services                                                                                                |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- |
| **Controller**      | Cloud control plane   | Xloud Identity, Xloud Dashboard, Xloud Compute API, Xloud Networking Server, MariaDB, RabbitMQ, HAProxy |
| **Network**         | Network agents        | L3 Router Agent, DHCP Agent (often combined with Controller)                                            |
| **Compute**         | Virtual machine hosts | Xloud Compute, Libvirt --- where VMs run                                                                |
| **Storage**         | Persistent volumes    | Xloud Block Storage volumes --- where VM disk data lives                                                |
| **Monitoring**      | Observability stack   | Prometheus, Grafana, logging services                                                                   |
| **XAVS-Deployment** | Ansible controller    | Runs deployment playbooks (usually the same server as Controller)                                       |
| **XSDS-Bootstrap**  | First storage node    | Bootstraps the Xloud Distributed Storage cluster                                                        |
| **XSDS**            | Storage nodes         | Additional Xloud Distributed Storage nodes                                                              |

<Info>
  A single server can hold multiple roles. In smaller deployments, it is common to combine Controller, Network, and XAVS-Deployment on the same server.
</Info>

***

## Hosts Tabs

The Hosts module is organized into four tabs. Each tab handles a distinct part of the cluster inventory and connectivity workflow.

<Tabs>
  <Tab title="Hosts" icon="server">
    The Hosts tab is where you register servers into the cluster inventory. Choose your deployment mode first (AIO or Multi-Node), then add hosts using one of three methods.

    Three ways to add hosts:

    <AccordionGroup>
      <Accordion title="Single Add" icon="plus" defaultOpen>
        Add one host at a time through the form. Enter hostname (e.g., xd1.example), IP address, SSH port (default 22), then select roles using the toggle buttons: Controller, Network, Compute, Storage, Monitoring, XAVS-Deployment, XSDS-Bootstrap, XSDS.

        Click **Ping** to verify connectivity before adding.
      </Accordion>

      <Accordion title="Bulk Paste" icon="copy">
        Paste multiple hosts, one per line: `hostname,ip,roles` (roles separated by `|` or `;`).

        ```text title="Example" theme={null}
        ctrl-01,192.168.1.10,controller|network|xavs-deployment
        compute-01,192.168.1.11,compute
        compute-02,192.168.1.12,compute|storage
        ```

        Click **Preview** to verify, **Ping All** to check connectivity, then **Commit** to add.
      </Accordion>

      <Accordion title="Import File" icon="upload">
        Upload a JSON or CSV file with host definitions. Download sample files for the correct format. Useful for replicating host configs across environments.
      </Accordion>
    </AccordionGroup>

    **Network Scanner**: Enter a subnet (e.g., `192.168.1.0/24`) and click **Scan Network** to discover responsive hosts automatically.

    **Node Inventory Table**: Shows all added hosts with columns for Hostname, IP, Port, Roles (as colored badges), Ping status, SSH status. Searchable and paginated with **Ping All** and **SSH Check All** buttons.

    <Tip>The inventory table generates the Ansible inventory file automatically — you never need to manually edit the nodes file.</Tip>
  </Tab>

  <Tab title="SSH Access" icon="key">
    SSH connectivity is required for XDeploy to remotely configure and deploy services on every node. The SSH Access tab handles key generation, distribution, and connectivity verification.

    <Steps titleSize="h3">
      <Step title="Select hosts" icon="users">
        Select which hosts to configure SSH for. Quick-select buttons: **ALL**, **CTRL**, **NET**, **COMP**, **STOR**. Individual checkboxes also available.
      </Step>

      <Step title="Configure credentials" icon="key">
        Enter the SSH username and password. Used **once** to copy the SSH public key — after that, password-based auth is no longer needed.
      </Step>

      <Step title="Initialize SSH" icon="lock">
        Generates an SSH key pair (if needed), distributes the public key to every selected host via `ssh-copy-id`.
      </Step>

      <Step title="Registry aliases" icon="globe">
        Adds `docker-registry` hostname to `/etc/hosts` on each node so all servers can pull container images from the local registry.
      </Step>

      <Step title="Verify" icon="circle-check">
        Tests SSH connectivity to every host. Green = ready for deployment, red = check credentials or firewall.
      </Step>
    </Steps>

    <Warning>
      After SSH keys are working, use **Disable Password Auth** to prevent brute-force attacks on production deployments.
    </Warning>
  </Tab>

  <Tab title="DNS" icon="globe">
    Manages hostname resolution across the cluster. Many services communicate using hostnames, not just IP addresses. This tab distributes hostname-to-IP mappings to `/etc/hosts` on every node.

    <Warning>If a compute node cannot resolve the controller hostname, internal API calls fail silently. Always verify DNS resolution after setup.</Warning>
  </Tab>

  <Tab title="Logs" icon="terminal">
    The Logs tab records all host management operations with timestamps --- SSH key distribution, host additions, connectivity tests, and DNS distribution results. Use this log to diagnose SSH failures or trace when hosts were added or modified.
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="settings" href="/deployment/configuration" color="#197560">
    Configure networking, storage, monitoring, and security settings for your deployment
  </Card>

  <Card title="Operations" icon="play" href="/deployment/operations" color="#197560">
    Deploy, upgrade, reconfigure, and manage cloud services across your cluster
  </Card>
</CardGroup>