Skip to content

get-started-guide.md

Latest commit

 

History

History
453 lines (322 loc) · 17.8 KB

get-started-guide.md

File metadata and controls

453 lines (322 loc) · 17.8 KB
Raw

Get Started

The Edge Microvisor Toolkit Standalone Node uses the standard immutable build. You can build your own bootable USB from source code, or use the downloadable ISO image that can be flashed to a USB device and installed on edge nodes. It installs the microvisor and Kubernetes to the edge node with the essential functionality to run a single node cluster. The edge node will serve as both the control and worker node. Additional worker nodes can be added to the cluster through Kubernetes.

The Standalone Edge Node can be included in Edge Manageability Framework, deployed on-premises or in the cloud to support scale out and management of larger infrastructures. It enables you to quickly get an edge node up and running without deploying backend services, ready to deploy Kubernetes applications through kubectl, helm, or Kubernetes web dashboard.

Standalone Node Provisioning

Create a Bootable USB Drive Using Source Code

A bootable USB drive can be created using the source code and your chosen version of the Edge Microvisor Toolkit Standalone Node. This process works for deployments using either kubernetes or container host_type configurations.

  • Edge Microvisor Toolkit Non-RT (standard kernel)
  • Edge Microvisor Toolkit Desktop Virtualization
  • Custom immutable Edge Microvisor Toolkit created using Edge Microvisor Toolkit Developer Node

Note: Make sure to update config-file according to the requirements of the custom Edge Microvisor Toolkit immutable image.

You can download or re-use your own custom EMT image and replace the default EMT image in the installer directory before creating the bootable USB drive.

See the diagram below to learn how USB-based provisioning of the standalone node works.

flowchart TD
   A[Clone the edge-microvisor-standalone-node repository from GitHub]
   A --> B{Choose your Edge Microvisor Toolkit image}
   B -- "Non-RT (default and applicable for most Edge AI apps)" --> C["Run: sudo make build\nauto-selects config-file-nrt and downloads K3s artifacts"]
   C --> D[Update config-file with your settings]
   D --> E[Create a bootable USB drive]
   E --> F[Plug the USB drive into the edge node and install]
   F --> G[Start using your edge node for AI apps or other use cases]
   B -- "Desktop Virtualization or custom image" --> H["Run: sudo make build INSTALL_TYPE=DV PLATFORM_TYPE=RPL\nauto-selects config-file-dv and downloads DV K3s artifacts"]
   H --> I[Update config-file with your settings]
   I --> J[Create a bootable USB drive using the installer]
   J --> K[Plug the USB into the edge node and install]
   K --> L[Start using your edge node for your specific use case]
Loading

Tip: For most users, the default Non-RT image is recommended. Advanced users can use other images as needed.

Step 1: Prepare

1.1: Repository Setup

Start by cloning the repository that holds all the essential scripts and configurations for deployment in the Ubuntu Linux system. This step is vital for obtaining the tools needed for the standalone node.

git clone https://github.com/open-edge-platform/edge-microvisor-toolkit-standalone-node
cd edge-microvisor-toolkit-standalone-node

1.2: Create the Standalone Installer with NRT or DV image

Running sudo make build will automatically:

  • Download the Microvisor image and Kubernetes artifacts for the selected INSTALL_TYPE

  • Select the correct config-file based on INSTALL_TYPE:

    • INSTALL_TYPE=NRT → uses config-file-nrt as config-file
    • INSTALL_TYPE=DV → uses config-file-dv as config-file

  • Package everything into standalone-installation-files.tar.gz

  • To create a standalone installation tar file using a Non-RT (NRT) image, run the following command:

    sudo make build

  • To create a standalone installation tar file with Display Virtualization (DV). This process integrates the DV image directly instead of the Non-RT image, eliminating the need for manual steps to replace Non-RT image with DV:

    Platform types available are PTL: Pantherlake, RPL: Raptorlake and BTL: Bartlettlake.

    Note: INSTALL_TYPE=DV is not supported for PTL platform. INSTALL_TYPE=NRT is supported for both RPL, BTL and PTL platforms.

    sudo make build INSTALL_TYPE=DV PLATFORM_TYPE=RPL

Note: This command will generate the standalone-installation-files.tar.gz file. The file will be located in the $(pwd)/installation_scripts/out directory.

1.3: Prepare the bootable USB Drive

Note:

  • Ensure the correct USB drive is selected to avoid data loss.
  • Replace /dev/sdX with the actual device name of your USB drive.

  • Insert the USB drive into the Developer's System and identify the USB disk:

    lsblk -o NAME,MAJ:MIN,RM,SIZE,RO,FSTYPE,MOUNTPOINT,MODEL

    Note: Ensure the correct USB drive is selected to avoid data loss.

  • Use the wipefs command to remove any existing filesystem signatures from the USB drive. This ensures a clean slate for formatting

    sudo wipefs --all --force /dev/sdX

  • Format the USB drive with a FAT32 filesystem using the mkfs.vfat command.

    sudo mkfs.vfat /dev/sdX

  • Unmount the USB drive to ensure the creation of bootable USB.

    • Check what is currently mounted:

      df -hT

    • Unmount the drive:

      sudo umount /dev/sdX

  • Copy the standalone installation tar file to developer system to prepare the Bootable USB drive.

    Extract the contents of standalone-installation-files.tar.gz:

     sudo tar -xzf standalone-installation-files.tar.gz

  • Extracted files will include

    bootable-usb-prepare.sh
write-image-to-usb.sh
config-file
usb-bootable-files.tar.gz
edgenode-logs-collection.sh
standalone-vm-setup.sh
download_images.sh

  • Download the Kubernetes artifacts (container images and manifest files): The config-file included in the archive is automatically pre-configured for the selected INSTALL_TYPE (NRT or DV). Kubernetes artifacts are also pre-downloaded and bundled during the sudo make build step — no manual download_images.sh execution is required. By default the script will only pull basic kubernetes artifacts to create a single-node cluster.

  • Update config-file with your deployment-specific settings.

    This configuration file is used to provision the edge node during its initial boot and should include the following parameters:

    • Proxy settings: Specify if the edge node requires a proxy to access external networks.
    • SSH key: Provide the public SSH key (typically your id_rsa.pub) from your Linux development system to enable passwordless SSH access to the edge node.
    • User credentials: Define the username and password for the primary user account on the edge node.
    • host_type: Choose the deployment type by providing the host_type input as kubernetes or container
      • If host_type is set to kubernetes, k3s will be installed on the EMT after successful provisioning
      • If host_type is set to container, Docker will be installed on the EMT after successful provisioning
      • Both cannot co-exist on the provisioned EMT image
    • Cloud-init customization: Optionally, include user-defined cloud-init configurations for advanced setup requirements.
      • For the default EMT non-RT image, a basic Kubernetes installation will be performed automatically.
      • For deployments requiring Desktop Virtualization features, refer to the desktop-virtualization-image-guide. This document provides cloud-init configurations that can be tailored to your specific deployment needs.
    • Hugepages configuration: Set hugepages parameters if your workloads require them.
    • NTP Configuration: By default, NTP is configured with time.google.com in the cloud-init config file.
      • To use a custom NTP server, set the USER_CUSTOM_NTP_SERVERS variable in the config-file with comma-separated ( for more than one NTP address ) NTP server addresses.

  • Run the preparation script to create the bootable USB drive:

    sudo ./bootable-usb-prepare.sh </dev/sdX> usb-bootable-files.tar.gz config-file

  • Required Inputs for the script:

     - usb: A valid USB device name (e.g., `/dev/sdc`)
 - usb-bootable-files.tar.gz: The tar file containing bootable files
 - config-file: Configuration file with deployment-specific settings

Note: Providing proxy settings is optional if the edge node does not require them to access internet services.

Additional Customization:

If you want to add specific configurations, helm charts, or packages to your deployment, you can refer to the pre-loading-user-apps guide for detailed instructions on customizing your EMT image.

1.4: Choose Your Edge Microvisor Toolkit Image

The Edge Microvisor Toolkit Standalone Node supports different EMT images to meet specific edge deployment needs. You can choose from:

  • Edge Microvisor Toolkit Non-RT image (default)
  • Edge Microvisor Toolkit Desktop Virtualization image
  • Customized immutable Edge Microvisor Toolkit created using "Edge Microvisor Toolkit Developer Node"
Option 1: Using the Default Non-RT Image

If you opt for the default non-RT image, which is suggested for the majority of Edge AI applications, run sudo make build (default). The build process will automatically:

  • Use config-file-nrt as the config-file
  • Download NRT-specific Kubernetes artifacts
  • Bundle everything into standalone-installation-files.tar.gz

There is no need for further image setup or manual config file selection.

Option 2: Using Desktop Virtualization or Custom created image

If you need Desktop Virtualization features, run sudo make build INSTALL_TYPE=DV PLATFORM_TYPE=RPL. The build process will automatically:

  • Use config-file-dv as the config-file
  • Download DV-specific Kubernetes artifacts
  • Bundle everything into standalone-installation-files.tar.gz

No manual config file copying or download_images.sh execution is needed for the standard DV flow.

For a custom image, follow the steps below to replace the default image after building:

  1. Download the desktop virtualization image (DV) from the "no Auth" file server registry. The DV image is available here Download DV Image Link to the sha256sum for this image

    Note: A custom image can be copied locally from your development system to the 5th partition, as shown in Step 2 below.

  2. Replace the default EMT image with the EMT DV image or custom image. The default EMT image is located at the 5th partition of the bootable USB drive created in the previous step. Follow these steps to replace the image:

    # Create a test directory for mounting.
sudo mkdir -p /mnt/test

# Mount the 5th partition of the USB drive.
sudo mount /dev/sda5 /mnt/test

# Navigate to the mounted directory.
cd /mnt/test

# Remove the older image (backup first if needed).
sudo rm -f <old-image-file>

# For Desktop Virtualization image: Download from registry.
sudo wget <your-dv-image-url> -O <new-image-file>

# For Custom created image: Copy from a local directory to the 5th partition.
sudo cp /path/to/your/custom-image.raw ./

# Unmount the partition.
cd /
sudo umount /mnt/test

Important: These steps are manually executed by the user to put the desired image into the 5th partition before deploying the edge node.

Step 2: Deploy Edge Node

  1. Unplug the attached bootable USB drive from the developer system.

  2. Plug the created bootable USB drive into the standalone node.

  3. Set the BIOS boot manager to boot from the USB drive.

  4. Reboot the Standalone Node

    This will start the Bootkit OS, followed by Microvisor installations.

  5. Automatic Reboot

    The standalone edge node will automatically reboot into Microvisor.

  6. First Boot Configuration

During the first boot, cloud-init will install the k3s Kubernetes cluster.

2.1 Login to the Edge Node After Installation

Refer to the edge node console output for instructions to verify the kubernetes cluster creation. Use the Linux login credentials which was provided while preparing the bootable USB drive.

Note: If you want to run kubectl, commands from the edge node you can use the provided k alias, which is defined in the .bashrc of the user defined in your config.

k get pods -A

Step 3: Set up tools on Developer's System

Install and configure kubectl and helm tools on the developer system.

Note: The commands are executed from Linux environment, but the same can be achieved from any environment supporting kubectl and helm by using equivalent commands.

  1. Install kubectl:

    sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
  https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /' | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

  2. Copy the kubeconfig file from the Edge Node:

    mkdir ~/.kube
export EN_IP=<EN_IP>
scp user@${EN_IP}:/etc/rancher/k3s/k3s.yaml ~/.kube/config

  3. Update the Edge Node IP in the kubeconfig file and export the path as KUBECONFIG:

    sed -i "s/127\.0\.0\.1/${EN_IP}/g" ~/.kube/config
export KUBECONFIG=~/.kube/config

  4. Test the connection:

    kubectl get pods -A

  5. Install helm:

    curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh

Step 4: Installing tools

When tools are not included in EMT (NRT/DV) immutable images, they can be installed on the Standalone edge Node using the following commands. Make sure to update the environment variables as needed.

# Install required tools like git, wget etc.
sudo http_proxy=http://<proxy-server>:<port> https_proxy=http://<proxy-server>:<port> dnf --installroot=/opt/user-apps/tools/ -y install git wget

# export environment variable needed by the tools
export PATH=$PATH:/opt/user-apps/tools/usr/bin:/opt/user-apps/tools/usr/sbin
export GIT_EXEC_PATH=/opt/user-apps/tools/usr/libexec/git-core
export GIT_TEMPLATE_DIR=/opt/user-apps/tools/usr/share/git-core/templates

# Example git clone 
http_proxy=http://<proxy-server>:<port> https_proxy=http://<proxy-server>:<port> git clone https://github.com/open-edge-platform/edge-ai-suites.git

# Check the installation:
user@EdgeMicrovisorToolkit [ ~ ]$ git --version
git version 2.45.4

Step 5: Install Sample Application

1. Deploy kubernetes application for host_type=kubernetes

  1. Install a Sample applications like WordPress or NGinx, using helm.

  2. View the running pods:

    kubectl get pods -n wordpress
NAME                           READY   STATUS    RESTARTS       AGE
my-wordpress-d57b44f9c-lw69m   1/1     Running   3 (3m4s ago)   10m
my-wordpress-mariadb-0         1/1     Running   0              10m

  3. Forward the port to get access to WP:

    kubectl port-forward --namespace wordpress svc/my-wordpress 8080:80

  4. Access the WP blog from browser using http://localhost:8080/admin URL.

  5. Login, using the admin (login) and password (<pass>) credentials

Note: Edge AI applications from the Edge Software Catalog can be installed using helm and evaluated using similar steps.

2. Deploying container application for host_type=container

  1. Install pre-requisite tools as explained in section "Installing tools"

  2. Install a Sample application like Pallet Defect Detection

Refer to get started document Get-Started Pallet Defect Detection

Step 6: Upgrade to the EMT

Edge Microvisor Toolkit Standalone Node supports upgrading to a newer version of EMT image via split A/B immutable update mechanism. For detailed instruction refer to emt-update-guide.

Troubleshooting

  1. Creation of a bootable USB drive failed

    The possible reason could be that the USB device is mounted. Please unmount it and retry creating the bootable USB drive.

  2. Issues while provisioning the microvisor

    If you encounter issues during microvisor provisioning with the EMT Bootkit, check the os-installer.log file located on partition 6 of the bootable USB device (e.g., /dev/sdX6). This log contains detailed error messages and troubleshooting information to help diagnose and resolve installation problems.

  3. Installation status banner

    After the successful installation, a summary is printed into terminal output. It shows the status of installation and provides useful commands/ paths to logs for further analysis and management.