Version: 3.0

Getting started with a single node installation

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

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

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)

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

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 file from the CubeCOS GitHub repository based on your preferred installation method.

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

Utilize the following tables to prepare information required for a cluster deployment.

CubeCOS node IP addresses and hostnames

CubeCOS node hostname	Management IP Address

A sample planner

CubeCOS node hostname	Management IP Address
control-converged	10.32.2.230

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

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

After preparing the installation media and booting the target machine. Start the installation 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.

At the uefi-installer login prompt, enter the following credentials.
1. Username: admin
2. Password: admin
Run restore to start the installation. The installer lists the available disks. Enter the index of the target disk, then confirm by entering YES.
```
uefi-installer> restore
 1: sda   238.5G   INTEL
 2: sdb   476.9G   SQF-S25V2-512GDSDC
Enter index: 1
Restoring CUBE_<version> 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.

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.
After the installation completes, reboot the system with:
1. Confirm by entering YES
```
reboot
```

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.

Use the default credentials to log in:

Username: admin
Password: admin

Choose a setup option - Wizard

Enter 1 to launch the interactive setup wizard.

    First Time Setup Options:
    1: Wizard
    2: Advanced
    Enter index: 1

Read and accept the EULA

Follow the prompts to read and accept the license terms.

    -- 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

By default, CubeCOS updates the password after set_ready. It uses the format [email protected], 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: [email protected].

To change the password manually:

    -- 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

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

    -- 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

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 section.

Skip to Configure an 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.

    -- 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

Skip to Configure an IP address for a specific interface if VLAN is not required.

    -- 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

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

    -- 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: <your-management-ip-address>
    Enter the IPv4 subnet mask: <your-subnet-mask>
    Enter the IPv4 default gateway: <your-gateway-address>

    -- 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

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.

    -- 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: <your-dns-server>

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.

    -- 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

In single-node deployments, select the control-converged role. This role combines control plane, compute, and storage functions on a single host.

    -- 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.

    - 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: <replace-with-your-secret> # 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

note

High availability (HA) is not supported for single-node deployments

Skip this step by pressing n:

    -- Cube High Availability --
    Current HA setting: disabled
    1: Change HA
    x: Exit
    p: Previous screen
    n: Next screen

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:

    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.

Verify success in the console

Policy changes were successfully applied.

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

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. You can pass it as arguments set_ready [<CIDR>] [<gateway>] [<IP,IP-IP>] or enter the values interactively when prompted.

    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 [email protected], where xxx.xxx are the last two octets of the cluster VIP. For example, with VIP 10.32.1.200 the password becomes [email protected]. Use this password for subsequent logins.

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

Open a browser on your local system.
Navigate to https://<your-management-ip-address> (for example, https://10.32.1.200).
Log in with:
1. Username: admin
2. Password: the password set during setup, or the [email protected] default generated by set_ready.
Once logged in, you can manage your CubeCOS environment through the web UI.

Troubleshooting

Resolve erroneous configuration.

If there are errors in the configuration, the installation process will fail and display an error message.

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.

    Policy changes could not be applied. System must be rebooted.
    Press enter to continue:

Resolve the `No images found` error

If the restore command returns the following error, the installer cannot locate the installation media:

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 the installer CLI and log in as root:

uefi-installer> exit

At the login prompt, enter the following credentials:

Username: root
Password: admin

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

Run lsblk to identify block devices and verify whether the installation media is mounted:

# 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 the installation partition to /mnt/install.
```
mount /dev/sdd1 /mnt/install
```

Verify the mount results.

# 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

Switch back to the admin user to resume the installation:

# 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 and continue.

Control-converged (AIO) node overview​

AIO node hardware requirements​

Processor​

Memory​

System Drive (Solid State Drive)​

Storage​

Download the installation files​

Supported installation options​

Prepare cluster information​

CubeCOS node IP addresses and hostnames​

Public network configuration​

Begin the installation process​

Log in and start the restore process​

Getting started from the CubeCOS console​

Login to begin installation​

Choose a setup option - Wizard​

Read and accept the EULA​

Change the password​

Configure hostname​

[Optional] Configure network bonding​

[Optional] Configure VLAN​

Configure an IP address for a specific interface​

Configure DNS servers​

Configure time zone​

Configure CubeCOS node role​

Configure High Availability​

Start policy application​

Exit and re-login to apply policy changes​

Initialize the cluster​

Verify the deployment​

Access the management interface​

Troubleshooting​

Resolve erroneous configuration.​

Resolve the No images found error​

Exit the installer CLI and open a root shell​

Verify block devices with lsblk​

Mount the installation media manually​

Return to the installer CLI and resume installation​

Control-converged (AIO) node overview

AIO node hardware requirements

Processor

Memory

System Drive (Solid State Drive)

Storage

Download the installation files

Supported installation options

Prepare cluster information

CubeCOS node IP addresses and hostnames

Public network configuration

Begin the installation process

Log in and start the restore process

Getting started from the CubeCOS console

Login to begin installation

Choose a setup option - Wizard

Read and accept the EULA

Change the password

Configure hostname

[Optional] Configure network bonding

[Optional] Configure VLAN

Configure an IP address for a specific interface

Configure DNS servers

Configure time zone

Configure CubeCOS node role

Configure High Availability

Start policy application

Exit and re-login to apply policy changes

Initialize the cluster

Verify the deployment

Access the management interface

Troubleshooting

Resolve erroneous configuration.

Resolve the `No images found` error

Exit the installer CLI and open a root shell

Verify block devices with lsblk

Mount the installation media manually

Return to the installer CLI and resume installation