Skip to main content
cubecos
Version: 3.0

Get started with a three node cluster

What is a Control Converged​

The Three-Node Cluster consists of three Control Converged Nodes, each integrating all core roles — Control, Compute, Network, and Storage into a single machine.

This setup provides high availability and clustering capabilities, making it suitable for testing, evaluation, or small-scale production environments.

aio-architecture

Hardware recommendation​

  1. Processor:

    • Any x86 CPU with a minimum of 8 Cores and 16 Threads (equivalent to 16 vCPUs) or better (Requires support for Intel VT-x or AMD-V).
    • Must be 64-bit and released after 2017.

  2. Memory:

    • At least 128GB of RAM.
    • Additional 1.7GB of RAM for each 1TB of usable software-defined-storage capacity.

  3. System Drive (Solid State Drive):

    • 1x 500GB Solid State Drive for the system drive (RAID-1 configuration required for production deployments).

  4. Storage:

    • Additional SSD/HDD for a storage pool, configured as JBOD (Just a Bunch Of Disks), HBA or single-disk RAID-0 for increased storage capacity.
    • Solid State Drive is required for Kubernetes cluster.

Downloading the installation files​

Navigate to the CubeCOS GitHub repository to download the installation files corresponding to your chosen installation method.

CubeCOS supports and provides installation medias for following installation methods:

  • Image via USB Flash Drive: Boot and install directly from a USB device.
  • ISO for Virtual Media or DVD: Mount the ISO using virtual media or burn it to a physical DVD for installation.
  • Network Boot via PXE Server (IMG/ISO): Deploy over the network using a PXE server with either image or ISO format.

Installation​

Once you have prepared your chosen installation media and booted the target machine from it, proceed to start the installation process.

Login and restore to setup CubeCOS​

info

Before starting the setup, verify the IP address and IP CIDR configuration. Ensure that:

  • The assigned IP address is within the correct subnet range.
  • The CIDR notation accurately reflects the intended network mask (e.g., /24 for 255.255.255.0).
  • There are no IP conflicts within the target network.

Default account/password: admin/admin

danger

Performing a restore on the selected disk will erase all existing data on that disk.

Ensure that you have backed up any important data before proceeding with the installation.

  1. Begin by typing restore and selecting the partition where you want to install. Once selected, enter YES to proceed.

  2. Once completed, type reboot and confirm by entering YES to reboot the system.

    /assets/get-started/quick_single.png

CubeCOS console banner​

Press F2 to begin the setup process.

/assets/get-started/quick_single_2.png

Login​

Login with the default admin and admin credential to start the installation.

Choose a setup options - Wizard​

Enter 1 to launch the setup wizard.

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

EULA​

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

[Optional]Change the password​

default : admin​

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

[IMPORTANT] The host name must be in lowercase.

A valid hostname must:

  • Contain only letters (a-z), numbers (0-9), and hyphens (-)
  • Be 64 characters or less in length
  • Be unique within the network
  • Start with only letters, not a hyphen or numbers
  • Not be entirely numeric

A valid hostname cannot contain:

  • Special characters (!@#$%^&*())
  • Underscores (_)
  • Spaces
    -- 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​

[IMPORTANT] If cable is connected, column [Speed] will present the status else N/A, WARNING: do not use bond0, bond1, bondx, bd0 as bonding name.​

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

    -- 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 IP address - IF.1​

    -- 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: 10.32.2.231
    Enter the IPv4 subnet mask: 255.255.0.0
    Enter the IPv4 default gateway: 10.32.0.254




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

DNS setting​

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

Timezone configuration​

info

Set the same time zone on all nodes within the cluster to ensure consistent timekeeping. This is critical for proper coordination of services and log synchronization across the cluster.

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

    - Change the Time Zone -
    Select a continent or ocean:
    1: Africa
    2: Americas
    3: Asia
    4: Atlantic Ocean
    5: Australia
    6: Europe
    7: Pacific Ocean
    8: Etc
    Enter index: 3


    Select a timezone:
    1: (UTC+02:00) Asia/Jerusalem
    2: (UTC+03:00) Asia/Kuwait
    3: (UTC+03:00) Asia/Riyadh
    ~~~~~~
    30: (UTC+08:00) Asia/Taipei
    ~~~~~~
    39: (UTC+12:00) Asia/Kamchatka
    Enter index: 30

Configure Role​

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

    - Change Role -
    Select a role:
    1: control
    2: compute
    3: storage
    4: control-converged
    5: edge-core
    6: moderator
    Enter index: 4
    Specify external IP/domain [optional]:
    Specify management interface: IF.1
    Specify provider interface: IF.1
    Specify overlay interface: IF.1
    Specify storage interface [frontend(,backend)]: IF.1
    Specify region ("RegionOne"):
    Specify cluster secret seed: bigstack
    Specify management CIDR ("10.254.0.0/16"):

Configure High Availability​

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

        Select option: 1

        - Change HA -
        High Available Cube:
        1: Yes
        2: No
        Enter index: 1
        Specify control virtual Hostname: control
        Specify control virtual IP: 10.32.2.230
        Specify control group hostname [HOST,HOST,...]: cc1,cc2,cc3
        Specify control group address [IP,IP,...]: 10.32.2.231,10.32.2.232,10.32.2.233

        -- Cube High Availability --
        Current HA setting: enabled
        Current Control Virtual Hostname: control
        Current Control Virtual IP: 10.32.2.230
        Current Control Group: cc1(10.32.2.231),cc2(10.32.2.232),cc3(10.32.2.233)
        1: Change HA
        x: Exit
        p: Previous screen
        n: Next screen

        Select option: n

Finalize, change the configuration summary before proceed​

[IMPORTANT] Please wait for the first control node apply policy complete before you continue to next node.​

    Summary
    Password has not been modified.
    Host name: control-converged
    IF.1
        Default interface.
        IPv4 Mode: Manual
        IPv4 Address: 10.32.2.231
        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: enabled
    Control Virtual Hostname: control
    Control Virtual IP: 10.32.2.230
    Control Group: cc1(10.32.2.231),cc2(10.32.2.232),cc3(10.32.2.233)
    High Availability: disabled
    1: Accept the configuration
    2: Cancel the configuration
    3: Modify the configuration

    Select option: 1

Error message​

If configuration errors are detected, the installation will fail and display an error message.

caution

Allow the node to reboot, then verify your configuration details and reconfigure the node before attempting installation again.

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

Post installation process​

Instruct the cluster to initialize the system accordingly by running the CLI command:

    cluster set_ready

This command only needs to be executed once on one of the control role nodes, which can be one of the following:

  • control
  • control-converged
  • edge-core
  • moderator
    # ssh admin@IPADDRESS
    Welcome to the Cube Appliance
    Enter "help" for a list of available commands
    controller> cluster set_ready
    Storage disk configurations.
    ============================================================
    GROUP: default
    ID  CLASS  WEIGHT   TYPE NAME       STATUS  REWEIGHT  PRI-AFF
    -1         1.63660  root default
    -3         1.63660      host cube1
    0    hdd  0.81830          osd.0       up   1.00000  1.00000
    1    hdd  0.81830          osd.1       up   1.00000  1.00000
    Create a shared external network?
    Enter 'YES' to confirm: YES
    Input public network in CIDR: 10.32.0.0/16
    Input gateway of public network: 10.32.0.254
    Enter public network available IP list [IP,IP-IP]: 10.32.2.100-10.32.2.200
    [1/7] Updating storage replication rule
    [2/7] Checking SDN services
    [3/7] 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/7] Starting cluster
    [5/7] Strengthening password
    [6/7] Cluster check and repair
            Service  Status  Report
        ClusterLink      ok  [ link(v) clock(v) dns(v) ]
        ClusterSys       ok  [ bootstrap(v) license(v) ]
    ClusterSettings      ok  [ etcd(v) nodelist(v) mongodb(v) ]
            HaCluster    ok  [ hacluster(v) ]
            MsgQueue     ok  [ rabbitmq(v) ]
            IaasDb       ok  [ mysql(v) ]
            VirtualIp    ok  [ vip(v) haproxy_ha(v) ]
            Storage      ok  [ ceph(v) ceph_mon(v) ceph_mgr(v) ceph_mds(v) ceph_osd(v) ceph_rgw(v) rbd_target(v) ]
        ApiService       ok  [ haproxy(v) httpd(v) nginx(v) api(v) skyline(v) memcache(v) ]
        SingleSignOn     ok  [ k3s(v) keycloak(v) ]
            Network      ok  [ neutron(v) ]
            Compute      ok  [ nova(v) cyborg(v) ]
            Baremetal    ok  [ ironic(v) ]
                Image    ok  [ glance(v) ]
            BlockStor    ok  [ cinder(v) ]
            FileStor     ok  [ manila(v) ]
        ObjectStor       ok  [ swift(v) ]
        Orchestration    ok  [ heat(v) ]
                LBaaS    ok  [ octavia(v) ]
            DNSaaS       ok  [ designate(v) ]
            K8SaaS       ok  [ rancher(v) ]
        InstanceHa       ok  [ masakari(v) ]
        BusinessLogic    ok  [ senlin(v) watcher(v) ]
            DataPipe     ok  [ zookeeper(v) kafka(v) ]
            Metrics      ok  [ monasca(v) telegraf(v) grafana(v) ]
        LogAnalytics     ok  [ filebeat(v) auditbeat(v) logstash(v) opensearch(v) opensearch-dashboards(v) ]
        Notifications    ok  [ influxdb(v) kapacitor(v) ]
    [7/7] Global Information Tracker
    Done

Post installation​

Access the management interface​

  1. Open a browser of your choice
  2. Navigate to https://<node-ip> to access the management interface.
  3. Login with the default credentials admin/ admin to get started!