Install Kubernetes Platform on Bare Metal Standard with Rook Storage

Overview

The Standard with Rook Storage deployment option is a standard installation with independent controller and worker nodes.

For more information, see Supported Deployment Models.

Standard with Rook Storage Installation Workflow

The following table shows the high-level installation flow for Standard with Rook Storage:

Step

Section

Description

1

Prepare and Plan

Gather prerequisites, prepare servers, and obtain the ISO image.

2

Install Software on Controller-0

Install the platform OS on the first server.

3

Bootstrap System on Controller-0

Run the Ansible bootstrap playbook to initialize services.

4

Configure Controller-0

Set up OAM, MGMT interfaces, and NTP.

5

Unlock Controller-0

Unlock and bring controller-0 into service.

6

Install Software on Controller-1 and Worker Nodes

PXE boot and install controller-1 and worker nodes.

7

Configure Controller-1

Set up OAM, MGMT interfaces on controller-1.

8

Unlock Controller-1

Unlock and bring controller-1 into service.

9

Configure Worker Nodes

Configure interfaces on worker nodes.

10

Unlock Worker Nodes

Unlock and bring worker nodes into service.

11

Configure Storage Nodes

Configure interfaces on storage nodes.

12

Unlock Storage Nodes

Unlock and bring storage nodes into service.

13

Install Rook Application Manifest and Helm-Charts

Deploy the Rook Ceph application.

14

Post-Installation Tasks

Complete post-installation configuration.

Prepare and Plan

Complete the following prerequisites before starting the StarlingX installation.

Note

By default, StarlingX uses IPv4. To use StarlingX with IPv6:

  • The entire infrastructure and cluster configuration must be IPv6, with the exception of the PXE boot network.

  • Not all external servers are reachable via IPv6 addresses (for example Docker registries). Depending on your infrastructure, it may be necessary to deploy a NAT64/DNS64 gateway to translate the IPv4 addresses to IPv6.

Preparing servers is the first step of the StarlingX installation procedure.

Prior to starting the StarlingX installation, ensure that the bare metal servers are in the following state:

  • Physically installed.

  • Cabled for power.

  • Cabled for networking.

    Far-end switch ports should be properly configured to realize the networking shown in the diagram earlier in this topic.

  • All disks are wiped.

    This ensures that servers will boot from either the network or USB storage, if present.

  • BIOS configured with Intel Virtualization (VTD, VTX)

    • Disabled for controller-only servers and storage servers.

    • Enabled for controller+worker (All-in-one) servers and worker servers.

  • The servers are powered off.

After the servers are ready, download the ISO and prepare the boot mechanism. For more information, see Prepare the ISO and Boot Method.

Install Software on Controller-0

Install the StarlingX software on the first server in the deployment.

This step performs a non-interactive installation of the StarlingX operating system and RPMs on the server’s first disk. After installation, the system reboots into the newly installed OS.

The initial server becomes controller-0 for the deployment.

  1. Insert the bootable USB into a bootable USB port on the host you are configuring as controller-0. Do one of the following:

    • Create a bootable USB drive with the StarlingX host installer ISO. See Create Bootable USB for instructions on how to create a bootable USB with the StarlingX ISO.

    • Set up a PXE boot server hosting the installer ISO on the same network as the server that will be used as the initial controller-0. See PXE Boot Controller-0 for details on how to set up a PXE boot server and PXE-boot the StarlingX load on controller-0.

  2. Power on the host.

  3. Attach to a console, ensure the host boots from the USB, and wait for the StarlingX Installer Menus.

  4. Make the following menu selections in the installer:

    1. First menu: Select ‘Standard Controller Configuration’

    2. Second menu: Select ‘Graphical Console’ or ‘Textual Console’ depending on your terminal access to the console port

  5. Wait for non-interactive install of software to complete and server to reboot. This can take 5-10 minutes, depending on the performance of the server.

Bootstrap System on Controller-0

Use the following procedure to initialize, or bootstrap, the StarlingX software on controller-0. Provide a minimal set of system configuration parameters in the Ansible override file to complete the bootstrap process.

After the bootstrap process completes:

  • The system runs the core StarlingX services on controller-0.

  • You can access all APIs and CLIs locally.

  • The services are not yet providing operational workloads.

Note

If a manual or unexpected reboot occurs during or before the completion of the bootstrap phase, specifically before you unlock controller-0, you must reinstall the system starting from the software installation step. Back up any updated bootstrap or deployment configuration files to an external location before reinstalling.

  1. Login to controller-0 as sysadmin / sysadmin and change the password when prompted. This is required only for the first login.

    Login: sysadmin
Password:
Changing password for sysadmin.
(current) UNIX Password: sysadmin
New Password:
(repeat) New Password:

  2. Verify and/or configure IP connectivity.

    External connectivity is required to run the Ansible bootstrap playbook. The StarlingX boot image will DHCP out all interfaces so the server may have obtained an IP address and have external IP connectivity if a DHCP server is present in your environment. Verify this using the ip addr and ping 8.8.8.8 commands.

    Otherwise, manually configure an IP address and default IP route. Use the PORT, IP-ADDRESS/SUBNET-LENGTH and GATEWAY-IP-ADDRESS applicable to your deployment environment.

    sudo ip address add <IP-ADDRESS>/<SUBNET-LENGTH> dev <PORT>
sudo ip link set up dev <PORT>
sudo ip route add default via <GATEWAY-IP-ADDRESS> dev <PORT>
ping 8.8.8.8

  3. Specify user configuration overrides for the Ansible bootstrap playbook. Create the override file in the system administrator’s home directory (for example, $HOME/localhost.yml). Ansible automatically detects and applies this file during the bootstrap process.

    Using a bootstrap override file, you can customize the Ansible bootstrap process during installation. This file lets you override the default settings defined in default.yml by specifying deployment-specific parameters, such as networking and system configuration.

    Refer to Ansible Bootstrap Configurations for instructions on creating the override file and for details on advanced Ansible bootstrap configuration scenarios.

    Important

    Some Ansible bootstrap parameters cannot be changed or are very difficult to change after installation is complete.

    Review the set of install-time-only parameters before installation and confirm that your values for these parameters are correct for the desired installation.

    Refer to Ansible install-time-only parameters for details.

  4. Run the Ansible bootstrap playbook:

    Note

    Before running the Ansible bootstrap playbook, it is important that you ensure that controller-0 server time is synchronized correctly. Run the following command:

    # check the current server time
$ date

# if the current server time is not correct, update the NTP Servers configuration.
For more information, see :ref:`Configure NTP Servers <configuring-ntp-servers-and-services-using-the-cli>`.

    ~(keystone_admin)]$ ansible-playbook --ask-vault-pass /usr/share/ansible/stx-ansible/playbooks/bootstrap.yml

    Wait for Ansible bootstrap playbook to complete. This can take 5-10 minutes, depending on the performance of the host machine.

    Note

    Use —ask-vault-pass if your overrides file has been encrypted with ansible-vault.

  1. Run the Ansible bootstrap playbook:

    ansible-playbook /usr/share/ansible/stx-ansible/playbooks/bootstrap.yml

    Wait for Ansible bootstrap playbook to complete. This can take 5-10 minutes, depending on the performance of the host machine.

Configure Controller-0

Controller-0 configuration includes setting up administrative access, configuring interfaces and network time synchronization.

  1. Acquire admin credentials:

    source /etc/platform/openrc

  2. Configure the OAM and MGMT interfaces of controller-0 and specify the attached networks. Use the OAM and MGMT port names, for example eth0, that are applicable to your deployment environment.

    OAM_IF=<OAM-PORT>
MGMT_IF=<MGMT-PORT>
system host-if-modify controller-0 lo -c none
IFNET_UUIDS=$(system interface-network-list controller-0 | awk '{if ($6=="lo") print $4;}')
for UUID in $IFNET_UUIDS; do
    system interface-network-remove ${UUID}
done
system host-if-modify controller-0 $OAM_IF -c platform
system interface-network-assign controller-0 $OAM_IF oam
system host-if-modify controller-0 $MGMT_IF -c platform
system interface-network-assign controller-0 $MGMT_IF mgmt
system interface-network-assign controller-0 $MGMT_IF cluster-host

  3. Configure NTP servers for network time synchronization:

    system ntp-modify ntpservers=0.pool.ntp.org,1.pool.ntp.org

  4. If required, and not already done as part of bootstrap, configure Docker to use a proxy server.

    1. List Docker proxy parameters:

      system service-parameter-list platform docker

    2. Refer to Docker Proxy Configuration for details about Docker proxy settings.

OpenStack-Specific Host Configuration

Important

This step is required only if the StarlingX OpenStack application (stx-openstack) will be installed.

  1. For OpenStack only: Assign OpenStack host labels to controller-0 in support of installing the stx-openstack manifest and helm-charts later.

    system host-label-assign controller-0 openstack-control-plane=enabled

  2. For OpenStack only: Configure the system setting for the vSwitch.

    StarlingX has OVS (kernel-based) vSwitch configured as default:

    • Runs in a container; defined within the helm charts of stx-openstack manifest.

    • Shares the core(s) assigned to the platform.

    If you require better performance, use OVS-DPDK (OVS with the Data Plane Development Kit, which is supported only on bare metal hardware):

    • Runs directly on the host (it is not containerized).

    • Requires that at least 1 core be assigned/dedicated to the vSwitch function.

    To deploy the default containerized OVS:

    system modify --vswitch_type none

    Do not run any vSwitch directly on the host, instead, use the containerized OVS defined in the helm charts of stx-openstack manifest.

    To deploy OVS-DPDK, run the following command:

    system modify --vswitch_type ovs-dpdk
system host-cpu-modify -f vswitch -p0 1 controller-0

    Once vswitch_type is set to OVS-DPDK, any subsequent nodes created will default to automatically assigning 1 vSwitch core for AIO controllers and 2 vSwitch cores for compute-labeled worker nodes.

    When using OVS-DPDK, configure vSwitch memory per NUMA node with the following command:

    system host-memory-modify -f <function> -1G <1G hugepages number> <hostname or id> <processor>

    For example:

    system host-memory-modify -f vswitch -1G 1 worker-0 0

    Configure VMs in an OVS-DPDK environment to use huge pages to enable networking. Use a flavor with the property: hw:mem_page_size=large

    Configure the huge pages for VMs in an OVS-DPDK environment on this host, assuming 1G huge page, with the following command:

    system host-memory-modify -1G <1G hugepages number> <hostname or id> <processor>

    For example:

    system host-memory-modify worker-0 0 -1G 10

    Note

    After you unlock controller-0, changing vswitch_type requires locking and unlocking all compute-labeled worker nodes (and/or AIO controllers) to apply the change.

Rook-Specific Host Configuration

Important

This step is required only if the StarlingX Rook application will be installed.

For Rook only: Assign Rook host labels to controller-0 in support of installing the rook-ceph-apps manifest/helm-charts later and add ceph-rook as storage backend:

system host-label-assign controller-0 ceph-mon-placement=enabled
system host-label-assign controller-0 ceph-mgr-placement=enabled
system storage-backend-add ceph-rook --confirmed

Unlock Controller-0

Unlock controller-0 in order to bring it into service:

system host-unlock controller-0

Controller-0 will reboot in order to apply configuration changes and come into service. This can take 5-10 minutes, depending on the performance of the host machine.

Install Software on Controller-1 and Worker Nodes

  1. Power on the controller-1 server and force it to network boot with the appropriate BIOS boot options for your particular server.

  2. As controller-1 boots, a message appears on its console instructing you to configure the personality of the node.

  3. On the console of controller-0, list hosts to see newly discovered controller-1 host (hostname=None):

    system host-list
+----+--------------+-------------+----------------+-------------+--------------+
| id | hostname     | personality | administrative | operational | availability |
+----+--------------+-------------+----------------+-------------+--------------+
| 1  | controller-0 | controller  | unlocked       | enabled     | available    |
| 2  | None         | None        | locked         | disabled    | offline      |
+----+--------------+-------------+----------------+-------------+--------------+

  4. Using the host id, set the personality of this host to ‘controller’:

    system host-update 2 personality=controller

    This initiates the install of software on controller-1. This can take 5-10 minutes, depending on the performance of the host machine.

  5. While waiting for the previous step to complete, power on the worker nodes. Set the personality to ‘worker’ and assign a unique hostname for each.

    For example, power on worker-0 and wait for the new host (hostname=None) to be discovered by checking ‘system host-list’:

    system host-update 3 personality=worker hostname=worker-0

    Repeat for worker-1. Power on worker-1 and wait for the new host (hostname=None) to be discovered by checking ‘system host-list’:

    system host-update 4 personality=worker hostname=worker-1

    For Rook storage, there is no storage personality. Some hosts with worker personality provide storage services. Here we still name these worker hosts storage-x. Repeat for storage-0 and storage-1. Power on storage-0, storage-1 and wait for the new host (hostname=None) to be discovered by checking ‘system host-list’:

    system host-update 5 personality=worker hostname=storage-0
system host-update 6 personality=worker hostname=storage-1

    Note

    A node with Edgeworker personality is also available. See Deploy Edgeworker Nodes for details.

  6. Wait for the software installation on controller-1, worker-0, and worker-1 to complete, for all servers to reboot, and for all to show as locked/disabled/online in system host-list.

    system host-list

+----+--------------+-------------+----------------+-------------+--------------+
| id | hostname     | personality | administrative | operational | availability |
+----+--------------+-------------+----------------+-------------+--------------+
| 1  | controller-0 | controller  | unlocked       | enabled     | available    |
| 2  | controller-1 | controller  | locked         | disabled    | online       |
| 3  | worker-0     | worker      | locked         | disabled    | online       |
| 4  | worker-1     | worker      | locked         | disabled    | online       |
| 5  | storage-0    | worker      | locked         | disabled    | online       |
| 6  | storage-1    | worker      | locked         | disabled    | online       |
+----+--------------+-------------+----------------+-------------+--------------+

Configure Controller-1

Configure the OAM and MGMT interfaces of controller-1 and specify the attached networks. Use the OAM and MGMT port names, for example eth0, that are applicable to your deployment environment.

(Note that the network install procedure partially sets up the MGMT interface automatically.)

OAM_IF=<OAM-PORT>
MGMT_IF=<MGMT-PORT>
system host-if-modify controller-1 $OAM_IF -c platform
system interface-network-assign controller-1 $OAM_IF oam
system interface-network-assign controller-1 $MGMT_IF cluster-host

OpenStack-Specific Host Configuration

Important

This step is required only if the StarlingX OpenStack application (stx-openstack) will be installed.

For OpenStack only: Assign OpenStack host labels to controller-1 in support of installing the stx-openstack manifest and helm-charts later.

system host-label-assign controller-1 openstack-control-plane=enabled

Rook-Specific Host Configuration

Important

This step is required only if the StarlingX Rook application will be installed.

For Rook only: Assign Rook host labels to controller-1 in support of installing the rook-ceph-apps manifest/helm-charts later:

system host-label-assign controller-1 ceph-mon-placement=enabled
system host-label-assign controller-1 ceph-mgr-placement=enabled

Unlock Controller-1

Unlock controller-1 in order to bring it into service:

system host-unlock controller-1

Controller-1 will reboot in order to apply configuration changes and come into service. This can take 5-10 minutes, depending on the performance of the host machine.

Configure Worker Nodes

  1. Assign the cluster-host network to the MGMT interface for the worker nodes:

    (Note that the MGMT interfaces are partially set up automatically by the network install procedure.)

    for NODE in worker-0 worker-1; do
   system interface-network-assign $NODE mgmt0 cluster-host
done

  2. Configure data interfaces for worker nodes. Use the DATA port names, for example eth0, that are applicable to your deployment environment.

    Important

    This step is required for OpenStack.

    This step is optional for Kubernetes: Do this step if using SR-IOV network attachments in hosted application containers.

    For Kubernetes SR-IOV network attachments:

    • Configure SR-IOV device plug in:

      for NODE in worker-0 worker-1; do
   system host-label-assign ${NODE} sriovdp=enabled
done

    • If planning on running DPDK in containers on this host, configure the number of 1G Huge pages required on both NUMA nodes:

      for NODE in worker-0 worker-1; do
   system host-memory-modify ${NODE} 0 -1G 100
   system host-memory-modify ${NODE} 1 -1G 100
done

    For both Kubernetes and OpenStack:

    DATA0IF=<DATA-0-PORT>
DATA1IF=<DATA-1-PORT>
PHYSNET0='physnet0'
PHYSNET1='physnet1'
SPL=/tmp/tmp-system-port-list
SPIL=/tmp/tmp-system-host-if-list

# configure the datanetworks in sysinv, prior to referencing it
# in the ``system host-if-modify`` command'.
system datanetwork-add ${PHYSNET0} vlan
system datanetwork-add ${PHYSNET1} vlan

for NODE in worker-0 worker-1; do
  echo "Configuring interface for: $NODE"
  set -ex
  system host-port-list ${NODE} --nowrap > ${SPL}
  system host-if-list -a ${NODE} --nowrap > ${SPIL}
  DATA0PCIADDR=$(cat $SPL | grep $DATA0IF |awk '{print $8}')
  DATA1PCIADDR=$(cat $SPL | grep $DATA1IF |awk '{print $8}')
  DATA0PORTUUID=$(cat $SPL | grep ${DATA0PCIADDR} | awk '{print $2}')
  DATA1PORTUUID=$(cat $SPL | grep ${DATA1PCIADDR} | awk '{print $2}')
  DATA0PORTNAME=$(cat $SPL | grep ${DATA0PCIADDR} | awk '{print $4}')
  DATA1PORTNAME=$(cat $SPL | grep ${DATA1PCIADDR} | awk '{print $4}')
  DATA0IFUUID=$(cat $SPIL | awk -v DATA0PORTNAME=$DATA0PORTNAME '($12 ~ DATA0PORTNAME) {print $2}')
  DATA1IFUUID=$(cat $SPIL | awk -v DATA1PORTNAME=$DATA1PORTNAME '($12 ~ DATA1PORTNAME) {print $2}')
  system host-if-modify -m 1500 -n data0 -c data ${NODE} ${DATA0IFUUID}
  system host-if-modify -m 1500 -n data1 -c data ${NODE} ${DATA1IFUUID}
  system interface-datanetwork-assign ${NODE} ${DATA0IFUUID} ${PHYSNET0}
  system interface-datanetwork-assign ${NODE} ${DATA1IFUUID} ${PHYSNET1}
  set +ex
done

OpenStack-Specific Host Configuration

Important

This step is required only if the StarlingX OpenStack application (stx-openstack) will be installed.

  1. For OpenStack only: Assign OpenStack host labels to the worker nodes in support of installing the stx-openstack manifest and helm-charts later.

    for NODE in worker-0 worker-1; do
    system host-label-assign $NODE openstack-compute-node=enabled
    kubectl taint nodes $NODE openstack-compute-node:NoSchedule
    system host-label-assign $NODE  openvswitch=enabled
    system host-label-assign $NODE dpdk=enabled
    system host-label-assign $NODE sriov=enabled
done

  2. For OpenStack only: Set up ‘instances’ filesystem, which is needed for stx-openstack nova ephemeral disks.

    for NODE in worker-0 worker-1; do
  echo "Configuring 'instances' for Nova ephemeral storage: $NODE"
  system host-fs-add ${NODE} instances=10
done

Unlock Worker Nodes

Unlock worker nodes in order to bring them into service:

for NODE in worker-0 worker-1; do
   system host-unlock $NODE
done

The worker nodes will reboot in order to apply configuration changes and come into service. This can take 5-10 minutes, depending on the performance of the host machine.

Configure Storage Nodes

  1. Assign the cluster-host network to the MGMT interface for the storage nodes.

    Note that the MGMT interfaces are partially set up by the network install procedure.

    for NODE in storage-0 storage-1; do
   system interface-network-assign $NODE mgmt0 cluster-host
done

  2. For Rook only: Assign Rook host labels to storage-0 in support of installing the rook-ceph-apps manifest/helm-charts later:

    system host-label-assign storage-0 ceph-mon-placement=enabled

Unlock Storage Nodes

Unlock storage nodes in order to bring them into service:

for STORAGE in storage-0 storage-1; do
   system host-unlock $STORAGE
done

The storage nodes will reboot in order to apply configuration changes and come into service. This can take 5-10 minutes, depending on the performance of the host machine.

Install Rook Application Manifest and Helm-Charts

On host storage-0 and storage-1:

  1. Erase GPT header of disk sdb.

    $ system host-disk-wipe -s --confirm storage-0 /dev/sdb
$ system host-disk-wipe -s --confirm storage-1 /dev/sdb

  2. Wait for the “rook-ceph-apps” application to be uploaded

    $ source /etc/platform/openrc

    ~(keystone_admin)]$ system application-list

  3. Edit values.yaml for rook-ceph-apps.

    cluster:
  storage:
    nodes:
    - name: storage-0
      devices:
      - name: /dev/disk/by-path/pci-0000:00:03.0-ata-2.0
    - name: storage-1
      devices:
      - name: /dev/disk/by-path/pci-0000:00:03.0-ata-2.0

  4. Update rook-ceph-apps override value.

    system helm-override-update rook-ceph-apps rook-ceph kube-system --values values.yaml

  5. Apply the rook-ceph-apps application.

    system application-apply rook-ceph-apps

  6. Wait for the OSDs pod to be ready.

    kubectl get pods -n kube-system
rook-ceph-mgr-a-ddffc8fbb-zkvln                     1/1     Running             0          66s
rook-ceph-mon-a-c67fdb6c8-tlbvk                     1/1     Running             0          2m11s
rook-ceph-mon-b-76969d8685-wcq62                    1/1     Running             0          2m2s
rook-ceph-mon-c-5bc47c6cb9-vm4j8                    1/1     Running             0          97s
rook-ceph-operator-6fc8cfb68b-bb57z                 1/1     Running             1          7m9s
rook-ceph-osd-0-689b6f65b-2nvcx                     1/1     Running             0          12s
rook-ceph-osd-1-7bfd69fdf9-vjqmp                    1/1     Running             0          4s
rook-ceph-osd-prepare-rook-storage-0-hf28p          0/1     Completed           0          50s
rook-ceph-osd-prepare-rook-storage-1-r6lsd          0/1     Completed           0          50s
rook-ceph-tools-84c7fff88c-x5trx                    1/1     Running             0          6m11s

Post-Installation Tasks

After completing the installation, perform the following post-installation tasks to fully configure and prepare the system for use. For more information, see Post-Installation Tasks.