Flatcar Installation (Bare Metal)

Here is a step-by-step guide on how to deploy the UMH stack on Flatcar Linux, a Linux distribution designed for container workloads, with high security and low maintenance.

This is a good option if you want to deploy the UMH stack on edge devices or IPCs.

Before you begin

Your system must meet the following requirements before you can install the United Manufacturing Hub:

• CPU: 2 cores
• RAM: 4 GB
• Storage: 10 GB

You need the latest version of our iPXE boot image:

• ipxe-x86_64-efi: for reasonably modern systems.
• ipxe-x86_64-bios: for older systems.
• ipxe-arm64-efi: for ARM systems. Currently, Raspberry Pi 4 is not supported.

The image needs to be written to a USB stick. If you want to know how to do this, follow our guide on how to flash an operating system onto a USB-stick.

You also need a computer with an SSH client (most modern operating systems already have it) and either UMHLens or OpenLens installed.

Additionally, this guide assumes a configuration similar to the following:

For optimal functionality, we recommend assigning a static IP address to your edge device. This can be accomplished through a static lease in the DHCP server or by setting the IP address during installation. Changing the IP address of the edge device after installation may result in certificate issues, so we strongly advise against doing so. By assigning a static IP address, you can ensure a more stable and reliable connection for your edge device.

Install Flatcar Linux on the edge device

1. Connect the USB stick to the edge device and boot it. Each device has a different way of booting from USB, so you need to consult the documentation of your device.
2. Accept the License.
3. Select the correct network settings. If you are unsure, select DHCP, but keep in mind that a static IP address is strongly recommended.
4. Select the correct drive to install Flatcar Linux on. If you are unsure, check the troubleshooting section.
5. Check that the installation settings are correct and press Confirm to start the installation.

Now the installation will start. You should see a green login prompt soon after, that says core@flatcar-0-install-<device-serial-number>. At this point the system is still installing. After a few minutes, depending on the speed of your network, the installation will finish and the system will reboot. Now you should see a login prompt that says flatcar-1-umh-<device-serial-number>, as well as the IP address of the device.

Connect to the edge device

Now you can leave the edge device and connect to it from your computer via SSH.

Open a terminal on your computer and connect to the edge device via SSH, using the IP address you saw on the login prompt:

ssh core@<ip-address>

If you are on Windows, you can use MobaXTerm to connect to the edge device via SSH. Open MobaXTerm and click on Session in the top left corner. Then click on SSH and enter the IP address of the edge device in the Remote host field. Click on Advanced SSH settings and enter core in the Username field. Click on Save and then on Open.

The default password for the core user is umh.

Import the cluster configuration

1. From your SSH session, run the following command to get the cluster configuration:

   sudo kubectl config view --raw
   

   The output should look similar to this:

   apiVersion: v1
   clusters:
   - cluster:
       certificate-authority-data: <long string>
       server: https://127.0.0.1:6443
     name: default
   contexts:
   - context:
       cluster: default
       user: default
     name: default
   current-context: default
   kind: Config
   preferences: {}
   users:
   - name: default
     user:
       client-certificate-data: <long string>
       client-key-data: <long string>
   

2. Copy the output.

3. Open UMHLens / OpenLens, click on the three horizontal lines in the upper left corner and choose Files > Add Cluster.

4. Paste the output.

5. Update the server field to the IP address of the device, e.g.:

   apiVersion: v1
   clusters:
   - cluster:
       certificate-authority-data: <long string>
       server: https://192.168.0.123:6443 # <- update this
   ...
   

6. If you want, you can also update the name field to something more meaningful, e.g.:

   apiVersion: v1
   clusters:
   - cluster:
       certificate-authority-data: <long string>
       server: https://192.168.0.123:6443
       name: my-edge-device # <- update this
   ...
   

7. Click on Add clusters.

Access the UMH stack

1. Open UMHLens / OpenLens on your device.

2. From the homepage, click on Browse Clusters in Catalog. You should see all your clusters.

3. Click on a cluster to connect to it.

4. Navigate to Helm > Releases and change the namespace from default to united-manufacturing-hub in the upper right corner.

   

   

5. Select the united-manufacturing-hub Release to inspect the release details, the installed resources, and the Helm values.

Troubleshooting

The installation stops at the green login prompt

To check the status of the installation, run the following command:

systemctl status installer

If the installation is still running, you should see something like this:

● installer.service - Flatcar Linux Installer
     Loaded: loaded (/usr/lib/systemd/system/installer.service; static; vendor preset: enabled)
     Active: active (running) since Wed 2021-05-12 14:00:00 UTC; 1min 30s ago

Otherwise, the installation failed. You can check the logs to see what went wrong.

I don’t know which drive to select

You can check the drive type from the manual of your device.

• For SATA drives (spinning hard disk or SSD), the drive type is SDA.
• For NVMe drives, the drive type is NVMe.

If you are unsure, you can boot into the edge device with any Linux distribution and run the following command:

lsblk

The output should look similar to this:

NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda      8:0    0 223.6G  0 disk
├─sda1   8:1    0   512M  0 part /boot
└─sda2   8:2    0 223.1G  0 part /
sdb      8:0    0  31.8G  0 disk
└─sdb1   8:1    0  31.8G  0 part /mnt/usb

In this case, the drive type is SDA. Generally, the drive type is the name of the first drive in the list, or at least the drive that doesn’t match the size of the USB stick.

I can access the cluster but there are no resources

First completely shut down UMHLens / OpenLens (from the system tray). Then start it again and try to access the cluster.

If that doesn’t work, access the edge device via SSH and run the following command:

systemctl status k3s

If the output contains a status different from active (running), the cluster is not running. Otherwise, the UMH installation failed. You can check the logs with the following commands:

systemctl status umh-install
systemctl status helm-install

If any of the commands returns some errors, is probably easier to reinstall the system.

What’s next

• You can follow the Getting Started guide to get familiar with the UMH stack.
• If you already know your way around the United Manufacturing Hub, you can follow the Administration guides to configure the stack for production.