Flatcar Installation (Virtual Machine)

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, in a virtual machine.

This is a good option if you want to deploy the UMH stack on a virtual machine to try out the installation process or to test the UMH stack.

Before you begin

You need the latest version of our iPXE boot image.

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 to have a virtual machine software installed on your computer. We recommend VirtualBox, which is free and open source, but other solutions are also possible.

Additionally, you need to have either UMHLens or OpenLens installed.

Create a virtual machine

Create a new virtual machine in your virtual machine software. Make sure to use the following settings:

• Operating System: Linux
• Version: Other Linux (64-bit)
• CPU cores: 2
• Memory size: 4 GB
• Hard disk size: 10 GB

Also, the network settings of the virtual machine must allow communication with the internet and the host machine. If you are using VirtualBox, you can check the network settings by clicking on the virtual machine in the VirtualBox manager and then on Settings. In the Network tab, make sure that the Adapter 1 is set to Bridged Adapter.

Install Flatcar Linux

1. Start the virtual machine.
2. Accept the License.
3. Set a static IP address.
4. Select sda as the disk.
5. Select Confirm.

Now the installation will start. You should see a green login prompt soon after, that says core@flatcar-0-install-0. 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.

By default, it will reboot into the installation environment. Just shut down the virtual machine and remove the ISO image from the CD drive, then boot the virtual machine again. This way, the installation process will continue, at the end of which you will a login prompt that says flatcar-1-umh-0, as well as the IP address of the device.

Connect to the virtual machine

You can leave the virtual machine running and connect to it using SSH, so that is easier to work with it.

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

I can’t SSH into the virtual machine

If you can’t SSH into the virtual machine, make sure that the network settings for the virtual machine are correct. If you are using VirtualBox, you can check the network settings by clicking on the virtual machine in the VirtualBox manager and then on Settings. In the Network tab, make sure that the Adapter 1 is set to NAT.

Disable any VPNs that you might be using.

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.