# Getting started with a single node installation > Set up CubeCOS with a single-node installation for fast deployment, minimal hardware use, and easy testing in lab or development environments. ## Control-converged (AIO) node overview {#control-converged-aio-node-overview} The AIO Node integrates all core roles into a single node, including control plane services, compute, networking, and storage. This all-in-one deployment runs CubeCOS with full functionality on a single machine, which is ideal for testing, evaluation, or small-scale environments. ## AIO node hardware requirements {#aio-node-hardware-requirements} ### Processor {#processor} - CubeCOS requires x86-64-v2 CPU with a minimum of 8 Cores and 16 Threads. - The processors used must support and have hardware virtualization enabled (Intel VT-x or AMD-V). - Must be 64-bit and released after 2017. ### Memory {#memory} - CubeCOS requires a minimum of 128GB of RAM for cluster services. - Reserve additional 1.7GB of RAM for each 1TB of usable software-defined-storage capacity. ### System Drive (Solid State Drive) {#system-drive-solid-state-drive} - **Minimum**: 1x 500GB Solid State Drive (SSD) for the system drive. - **Production**: Configure RAID-1 with two SSDs for redundancy and fault tolerance in production environments. ### Storage {#storage} - CubeCOS requires additional persistent storage such as SSD, HDD, or NVMe for the storage pool. - CubeCOS supports the following storage configuration: - JBOD (Just a Bunch Of Disks) - HBA (Host Bus Adapter) - Flash-based (SSD) storage are required for Kubernetes workloads. ## Download the installation files {#download-the-installation-files} Download the installation file from the [CubeCOS GitHub repository](https://github.com/bigstack-oss/cubecos/releases/latest) based on your preferred installation method. ### Supported installation options {#supported-installation-options} - **USB flash drive**: Create a bootable USB IMG to install CubeCOS directly. - **ISO for Virtual Media or DVD**: Mount the ISO using virtual media or burn to a DVD for installation. - **Network Boot via PXE Server (IMG/ISO)**: Install over the network using a PXE server with IMG or ISO format. ## Prepare cluster information {#prepare-cluster-information} Utilize the following tables to prepare information required for a cluster deployment. ### CubeCOS node IP addresses and hostnames {#cubecos-node-ip-addresses-and-hostnames} | CubeCOS node hostname | Management IP Address | | --------------------- | --------------------- | | | | :::info[A sample planner] | CubeCOS node hostname | Management IP Address | | --------------------- | --------------------- | | control-converged | 10.32.2.230 | ::: ### Public network configuration {#public-network-configuration} For the quickstart guide, use the following cluster information: - **Public network**: Network that allows access to the internet or to internal resources. - **Flat network**: Flat Networking uses Ethernet interfaces set up in bridge mode to enable seamless network traffic flow between all nodes. This configuration can be implemented using either a single network adapter on the physical host or multiple adapters, depending on the setup. - **DHCP IP Pool**: The available DHCP IP pool is in the same flat network and from a range of 100 to 200. Before proceeding, confirm that: - The selected subnet doesn’t overlap with other networks in your environment. - The gateway IP is reachable from within the subnet. - The DHCP range is not in use by other services and has enough available IPs for your expected VM instances. - The CIDR and gateway are correctly configured to allow external access if required (e.g., internet, upstream routers, etc.). You’ll configure the public network during the `cluster set_ready` process. :::warning Chanage the public network and DHCP IP range to what is applicable in your network. ::: | Public network CIDR | Public network gateway address | DHCP IP pool range | | ------------------- | ------------------------------ | ------------------ | | | | | :::info[Sample public network configuration] | Public network CIDR | Public network gateway address | DHCP IP pool range | | ------------------- | ------------------------------ | ----------------------- | | 10.32.0.0/16 | 10.32.0.254 | 10.32.2.100-10.32.2.200 | ::: ## Begin the installation process {#begin-the-installation-process} After preparing the installation media and booting the target machine. Start the installation process. ### Log in and start the restore process {#log-in-and-start-the-restore-process} :::info Before you begin setup, verify the network settings: - Ensure that the assigned IP address is within the correct subnet range. - Confirm that the CIDR notation reflects the intended network mask (e.g., /24 for 255.255.255.0). - Make sure there are no IP conflicts within the target network. ::: :::danger The restore operation **erases all data** on the selected disk. Backup any important data before proceeding. ::: 1. At the `uefi-installer` login prompt, enter the following credentials. 1. **Username**: `admin` 2. **Password**: `admin` 2. Run `restore` to start the installation. The installer lists the available disks. Enter the **index** of the target disk, then confirm by entering `YES`. ```bash uefi-installer> restore 1: sda 238.5G INTEL 2: sdb 476.9G SQF-S25V2-512GDSDC Enter index: 1 Restoring CUBE_ on /dev/sda Enter 'YES' to confirm: YES ``` :::info On a node with multiple disks, choose the disk intended for the operating system. Any additional disks are used for the storage pool. ::: :::info[Resolving the `No Images Found` error] If the installer returns a `hex_install: Error: No images found` error, resolve the issue following [Resolve the `No images found` error](#resolve-no-images-found-error). ::: 3. After the installation completes, reboot the system with: 1. Confirm by entering `YES` ```bash reboot ``` ### Getting started from the CubeCOS console {#getting-started-from-the-cubecos-console} After completing the `restore` process and rebooting, you'll see the CubeCOS setup banner. Press `F2` to begin the setup process. ### Login to begin installation {#login-to-begin-installation} Use the default credentials to log in: - Username: `admin` - Password: `admin` ### Choose a setup option - Wizard {#choose-a-setup-option---wizard} Enter `1` to launch the interactive setup wizard. ```bash First Time Setup Options: 1: Wizard 2: Advanced Enter index: 1 ``` ### Read and accept the EULA {#read-and-accept-the-eula} Follow the prompts to read and accept the license terms. ```bash -- Welcome -- Welcome to the Cube Appliance setup wizard. Using this setup wizard, you can: * View and accept the Software License Agreement * Set the appliance password * View and configure networking Press Enter to continue. -- Software License Agreement -- Currently selected language: English 1: Select language for license display 2: Read Bigstack terms 3: Read non-Bigstack terms 4: Proceed to acceptance Select option: 4 By choosing 'I agree,' you agree that (1) you have had the opportunity to review the terms of licenses presented above and (2) such terms govern this transaction. If you do not agree, choose 'I do not agree'. 1: I agree 2: I do not agree Select option: 1 ``` ### Change the password {#change-the-password} By default, CubeCOS updates the password after `set_ready`. It uses the format `Cube@xxx.xxx`, where `xxx.xxx` are the last two octets of the cluster's VIP. :::note If the cluster VIP is `192.168.100.100`, the updated default password will be: `Cube@100.100`. ::: To change the password manually: ```bash -- Appliance Password -- Password changes are applied immediately. Password has not been modified. 1: Change password x: Exit p: Previous screen n: Next screen Select option: 1 - Change Password - Enter old password: admin Enter new password: Confirm new password: Password successfully changed. ``` ### Configure hostname {#configure-hostname} :::warning A valid hostname must be in lowercase and cannot contain special characters (!@#$%^&\*()), underscores (\_), or spaces. ::: A valid hostname must: - Contain only lowercase letters (a-z), numbers (0-9), and hyphens (-) - Be 64 characters or less in length - Be unique within the network - Must start with a letter - Not be entirely numeric ```bash -- Host Name Configuration -- Host name: unconfigured 1: Change the host name x: Exit p: Previous screen n: Next screen Select option: 1 - Change the Host Name - Enter the new host name: control-converged -- Host Name Configuration -- Host name: control-converged 1: Change the host name x: Exit p: Previous screen n: Next screen Select option: n ``` ### [Optional] Configure network bonding {#optional-configure-network-bonding} Network bonding is optional and only required for deployments that require network redundancy. To better understand network configuration options and deployment scenarios, refer to the [network configuration](../category/network) section. Skip to [Configure an IP address for a specific interface](#configure-ip-address-for-a-specific-interface) if bonding and VLAN are not required. :::info If a network cable is connected, the `[Speed]` column will display the link status (e.g., 1000Mb/s, 10Gb/s). If no cable is detected, it will show `N/A`. ::: :::warning Do not use system reserved names such as `bond0`, `bond1`, `bondx`, or `bd0` as bonding interface names. ::: ```bash -- Network Bonding Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display policy 2: Configure network bonding x: Exit p: Previous screen n: Next screen Select option: n ``` ### [Optional] Configure VLAN {#optional-configure-vlan} Skip to [Configure an IP address for a specific interface](#configure-ip-address-for-a-specific-interface) if VLAN is not required. ```bash -- VLAN Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display policy 2: Configure vlan network x: Exit p: Previous screen n: Next screen Select option: n ``` ### Configure an IP address for a specific interface {#configure-ip-address-for-a-specific-interface} Assign your management IP address to a static IPv4 address, subnet mask, and default gateway on the primary interface. This guide assumes a single network interface labelled IF.1. Before proceeding, make sure you have the following information: - The static IP address for the CubeCOS management IP - The subnet mask of the management network - The default gateway for the subnet - The IP addresses of DNS servers to be used ```bash -- Networking Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display device status 2: Display policy 3: Configure IF.1 x: Exit p: Previous screen n: Next screen Select option: 3 - Configure IF.1 - Enter the IPv4 address: Enter the IPv4 subnet mask: Enter the IPv4 default gateway: -- Networking Settings -- --------------------------------------------------- Label BusID/Slaves Driver State Speed --------------------------------------------------- IF.1 0000:04:00.0 r8169 UP 1000F --------------------------------------------------- 1: Display device status 2: Display policy 3: Configure IF.1 x: Exit p: Previous screen n: Next screen Select option: n ``` ### Configure DNS servers {#configure-dns-servers} Enter the DNS servers that CubeCOS should use, this can be internal or external DNS resolves. Set up to three DNS servers to use. The following example has been provided for setting an external DNS server at `1.1.1.1`. ```bash -- DNS Configuration -- No DNS servers configured. 1: Set DNS server 1 2: Set DNS server 2 3: Set DNS server 3 x: Exit p: Previous screen n: Next screen Select option: 1 - Set DNS Server 1 - Enter the DNS server IP address: ``` ### Configure time zone {#configure-time-zone} :::info Set the same timezone on all nodes in the cluster. Consistent timekeeping is critical for coordinating services, ensuring accurate log timestamps, and avoiding synchronization issues. ::: To configure the time zone, select option `1`. ```bash -- Time Configuration -- Time configuration changes are applied immediately. Time Zone: America/New_York Date: 05/29/2025 Time: 14:00:37 1: Change the time zone 2: Change the date 3: Change the time x: Exit p: Previous screen n: Next screen Select option: 1 ``` ### Configure CubeCOS node role {#configure-cubecos-node-role} In single-node deployments, select the control-converged role. This role combines control plane, compute, and storage functions on a single host. ```bash -- Cube Role -- Current role: undef Current Management: IF.1 Current Domain/Region: default/RegionOne Current Cube Secret Seed: N/A 1: Change role x: Exit p: Previous screen n: Next screen Select option: 1 ``` When prompted, enter the following values: :::warning The cluster secret seed serves as an input variable for cryptographic value generation. Set a unique and strong value to ensure secure cluster communications and cryptographic operations. ::: ```bash - Change Role - Select a role: 1: control 2: compute 3: storage 4: control-converged 5: edge-core 6: moderator Enter index: 4 # Select control-converged role Specify external IP/domain [optional]: # Leave blank Specify management interface: IF.1 # Interface for control/API traffic Specify provider interface: IF.1 # Interface for VM data and external bridge Specify overlay interface: IF.1 # Interface used for internal SDN tunnel traffic Specify storage interface [frontend(,backend)]: IF.1 # Interface for Ceph traffic Specify region ("RegionOne"): # Keep default or customize as needed Specify cluster secret seed: # Unique secret shared among nodes in the same cluster Specify management CIDR ("10.254.0.0/16"): # (Optional) Change only if there is a subnet conflict, must be /16 subnet ``` ### Configure High Availability {#configure-high-availability} :::note High availability (HA) is not supported for single-node deployments ::: Skip this step by pressing `n`: ```bash -- Cube High Availability -- Current HA setting: disabled 1: Change HA x: Exit p: Previous screen n: Next screen ``` ### Start policy application {#start-policy-application} Review the configuration summary carefully before proceeding. You can modify settings if necessary. When ready to begin installation, select option `1` to apply the configuration: ```bash Summary Password has not been modified. Host name: control-converged IF.1 Default interface. IPv4 Mode: Manual IPv4 Address: 10.32.2.230 IPv4 Netmask: 255.255.0.0 IPv4 Gateway: 10.32.0.254 IPv6 Mode: Automatic DNS server 1: 1.1.1.1 Time Zone: Asia/Taipei Date: 05/29/2025 Time: 14:54:19 Role: control-converged External IP/Domain: N/A Management: IF.1 Provider: IF.1 Overlay: IF.1 Storage: IF.1 Domain/Region: default/RegionOne Cube Secret Seed: bigstack Management CIDR: 10.254.0.0/16 High Availability: disabled 1: Accept the configuration 2: Cancel the configuration 3: Modify the configuration Select option: 1 ``` The time required to apply the configuration may vary depending on system hardware performance. Monitor the console output. When the process completes successfully, you’ll see a confirmation message. :::tip[Verify success in the console] Policy changes were successfully applied. ::: ### Exit and re-login to apply policy changes {#exit-and-re-login-to-apply-policy-changes} After the policy has been successfully applied, log out and log back into the console to ensure the changes take effect and are reflected in the interface. After logging back in, the console status screen reports the node as `services ready` with the role counts `1 x control`, `1 x compute`, and `1 x storage`. ### Initialize the cluster {#cluster-initialization} Initialize the system by running the `cluster set_ready` CLI command. This step is required to bring the single node into an operational state. This command prepares the cluster for operation by: - Verifying and activating storage devices. - Applying storage replication policies (adjusted for the single-node topology). - Initializing core platform services (compute, networking, storage, identity, monitoring, etc.). - Configuring the shared external network. :::warning Run `cluster set_ready` only once. At least one Ceph OSD must be `up` first, otherwise the command aborts with `set_ready aborted due to zero running osd for cluster storage`. ::: Provide the public network configuration prepared in [Public network configuration](#public-network-configuration). You can pass it as arguments `set_ready [] [] []` or enter the values interactively when prompted. ```bash control-converged> cluster control-converged:cluster> set_ready 10.32.0.0/16 10.32.0.254 10.32.1.100-10.32.1.110 Storage disk configurations. ============================================================ GROUP: default ID CLASS WEIGHT TYPE NAME STATUS REWEIGHT PRI-AFF -1 0.46500 root default -3 0.46500 host control-converged 0 ssd 0.23250 osd.0 up 1.00000 1.00000 1 ssd 0.23250 osd.1 up 1.00000 1.00000 [1/6] Updating storage replication rule [2/6] Checking SDN services [3/6] Configuring modules (1/5) processing: cube_last (2/5) processing: octavia (3/5) processing: influxdb (4/5) processing: opensearch-dashboards (5/5) processing: kafka [4/6] Starting cluster [5/6] Strengthening password [6/6] Cluster check and repair Done ``` When `Done` is displayed and all services report `ok`, the cluster is ready. :::note During the `[5/6] Strengthening password` step, CubeCOS replaces the default `admin` password with one in the format `Cube@xxx.xxx`, where `xxx.xxx` are the last two octets of the cluster VIP. For example, with VIP `10.32.1.200` the password becomes `Cube@1.200`. Use this password for subsequent logins. ::: ### Verify the deployment {#verify-the-deployment} Confirm the node is healthy: - The console status screen shows `services ready` and `1 x control / 1 x compute / 1 x storage`. - Storage is healthy: from a root shell, `ceph -s` reports `health: HEALTH_OK` (the `[1/6] Updating storage replication rule` step clears the `undersized/degraded` warning expected on a single host before `set_ready`). ### Access the management interface {#access-the-management-interface} 1. Open a browser on your local system. 2. Navigate to `https://` (for example, `https://10.32.1.200`). 3. Log in with: 1. Username: `admin` 2. Password: the password set during setup, or the `Cube@xxx.xxx` default generated by `set_ready`. 4. Once logged in, you can manage your CubeCOS environment through the web UI. ## Troubleshooting {#troubleshooting} ### Resolve erroneous configuration. {#resolve-erroneous-configuration} If there are errors in the configuration, the installation process will fail and display an error message. :::caution[Reboot required] Allow the node to reboot before retrying. After rebooting, carefully review your configuration settings and make any necessary corrections before attempting the installation again. ::: ```bash Policy changes could not be applied. System must be rebooted. Press enter to continue: ``` ### Resolve the `No images found` error {#resolve-no-images-found-error} If the `restore` command returns the following error, the installer cannot locate the installation media: ```bash uefi-installer> restore hex_install: Error: No images found Unexpected error uefi-installer> ``` To resolve this, manually mount the installation media by completing the following steps. #### Exit the installer CLI and open a root shell {#exit-installer-open-root-shell} Exit the installer CLI and log in as `root`: ```bash uefi-installer> exit ``` At the login prompt, enter the following credentials: - **Username:** `root` - **Password:** `admin` ```bash uefi-installer login: root Password: Last login: Mon Jul 11 06:49:03 on ttyS0 Welcome to the Cube Appliance Installer # ``` #### Verify block devices with lsblk {#verify-block-devices-lsblk} Run `lsblk` to identify block devices and verify whether the installation media is mounted: ```bash # lsblk ``` If the installation USB drive (for example, `sdd1`) has no listed mount point, proceed to the next step. #### Mount the installation media manually {#mount-installation-media-manually} 1. Mount the installation partition to `/mnt/install`. ```bash mount /dev/sdd1 /mnt/install ``` 2. Verify the mount results. ```bash # lsblk NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT sda 8:0 0 744.6G 0 disk ├─sda1 8:1 0 1000M 0 part ├─sda2 8:2 0 2G 0 part ├─sda5 8:5 0 357.4G 0 part ├─sda6 8:6 0 357.4G 0 part └─sda7 8:7 0 26.9G 0 part sdb 8:16 0 5.1T 0 disk ├─sdb1 8:17 0 400M 0 part ├─sdb2 8:18 0 400M 0 part ├─sdb3 8:19 0 2.6T 0 part └─sdb4 8:20 0 2.6T 0 part sdc 8:32 0 5.1T 0 disk ├─sdc1 8:33 0 400M 0 part ├─sdc2 8:34 0 400M 0 part ├─sdc3 8:35 0 2.6T 0 part └─sdc4 8:36 0 2.6T 0 part sdd 8:48 1 28.7G 0 disk └─sdd1 8:49 1 5.7G 0 part /mnt/install sr0 11:0 1 1024M 0 rom sr1 11:1 1 1024M 0 rom ``` Confirm that `sdd1` now shows `/mnt/install` as its mount point. #### Return to the installer CLI and resume installation {#return-installer-cli-resume-installation} Switch back to the `admin` user to resume the installation: ```bash # su admin Welcome to the Cube Appliance Installer Welcome to the Cube Appliance Enter "help" for a list of available commands uefi-installer> ``` Return to [Begin the installation process](#begin-the-installation-process) and continue.