From 28a9469df64781833d67ec970b5d874cb6d2c046 Mon Sep 17 00:00:00 2001 From: Lenny Chen <55669665+lennessyy@users.noreply.github.com> Date: Thu, 25 Jan 2024 08:48:52 -0800 Subject: [PATCH] docs: add instructions for connecting edge host to wifi (#2092) * docs: add instructions for connecting edge host to wifi * edit yaml * vale vocab * remove reference to intel nuc * address comments * Apply suggestions from code review Co-authored-by: Karl Cardenas * replace wpa link with official manual link * remove problematic symbols * resolve conflicts * Apply suggestions from code review Co-authored-by: caroldelwing * address comments * prettier format --------- Co-authored-by: Lenny Chen Co-authored-by: Karl Cardenas Co-authored-by: caroldelwing --- .../clusters/edge/networking/connect-wifi.md | 145 ++++++++++++++++++ .../clusters/edge/networking/networking.md | 1 + .../site-installation/site-user-data.md | 91 ++++++++--- vale/styles/Vocab/Internal/accept.txt | 1 + 4 files changed, 213 insertions(+), 25 deletions(-) create mode 100644 docs/docs-content/clusters/edge/networking/connect-wifi.md diff --git a/docs/docs-content/clusters/edge/networking/connect-wifi.md b/docs/docs-content/clusters/edge/networking/connect-wifi.md new file mode 100644 index 0000000000..9cec65a755 --- /dev/null +++ b/docs/docs-content/clusters/edge/networking/connect-wifi.md @@ -0,0 +1,145 @@ +--- +sidebar_label: "Connect Edge Host to Wifi" +title: "Connect Edge Host to Wifi" +description: "Learn how to connect an Edge host to Wi-Fi using wpa_supplicant." +hide_table_of_contents: false +sidebar_position: 80 +tags: ["edge"] +--- + +This how-to walks you through how to connect an Edge host to a Wi-Fi network with +[wpa_supplicant](https://linux.die.net/man/8/wpa_supplicant), using an Intel mini-PC as an example. You can apply the +steps in this how-to with other hardware, but steps for configuring the network interface might be different. + +To connect an Edge host to Wi-Fi using `wpa_supplicant`, you need to build `wpa_supplicant` into the Operating System +(OS) image used for the Edge host and provide the Wi-Fi credentials to the Edge host. Depending on how Edge devices are +managed at an organization, these two steps are often done by different teams. If they are being done by the same team +or person, you can merge the user-data in the step [Supply Site-Specific User Data](#supply-site-specific-user-data) +with the original user data you use to build Edge artifacts and skip that step. + +## Build OS Image with wpa_supplicant Included + +### Prerequisites + +- A physical or virtual Linux machine with AMD64 (also known as x86_64) processor architecture to build the Edge + artifacts. You can issue the following command in the terminal to check your processor architecture. + + ```shell + uname -m + ``` + +- Minimum hardware configuration of the Linux machine: + - 4 CPU + - 8 GB memory + - 50 GB storage +- A bootable device such as a USB drive, or a Preboot Execution Environment (PXE) server. +- A [Spectro Cloud](https://console.spectrocloud.com/) account. If you have not signed up, you can sign up for a + [free trial](https://www.spectrocloud.com/free-tier/). +- A Palette registration token for pairing Edge hosts with Palette. You will need tenant admin access to Palette to + generate a new registration token. For detailed instructions, refer to the + [Create Registration Token](../site-deployment/site-installation/create-registration-token.md) guide. + +### Procedure + +1. Clone the CanvOS repository. + + ```shell + git clone https://github.com/spectrocloud/CanvOS.git + ``` + +2. Edit the file **Dockerfile** in the root directory of the repository. At the bottom of the file, add the following + lines. + + ``` + RUN apt-get update && apt-get install wpasupplicant && \ + mkdir /var/lib/wpa + ``` + + :::tip + + Consider including some other lightweight network utilities in the OS image that can help you troubleshoot or set up + network configurations alternatively if needed. For example, if you are using Ubuntu, consider replacing the RUN + statement with the following to also include network manager and ping. + + ``` + RUN apt-get update && apt-get install wpasupplicant -y && \ + apt-get update && apt-get install network-manager -y && \ + apt-get install iputils-ping -y && \ + mkdir /var/lib/wpa + ``` + + ::: + +3. Follow the rest of the steps in the guide [Build Edge Artifact](../edgeforge-workflow/palette-canvos.md). When + finished, identify the **palette-edge-installer.iso** file in the **build** folder. +4. Plug in your bootable device and flash it with the ISO image. +5. Plug the bootable device into the Edge host and power on the Edge host. When the Edge host powers on, open the boot + menu by pressing F10, and select the bootable device as your boot volume. +6. Wait for installation to finish. The Edge host will reboot by default upon completion unless you specify a different + option in the Edge Installer configuration user data. + +### Validate + +You can validate that the Edge host is ready for the site installation by powering on the Edge host and simulating a +site deployment. The simulation process will require you to complete the installation process and reset the device after +the validation. + +## Supply Site-Specific User Data + +It is likely that your Wi-Fi network name and passwords are site-specific, which means you won't be able to include the +network credentials in the installer. You can use site-specific user data to provide this information to you Edge hosts +instead. + +### Prerequisites + +- A bootable device such as a USB drive, or a Preboot Execution Environment (PXE) server. +- `mkisofs`, or `genisoimage`, or similar ISO management software. + - `cdrtools` or `wodim` for Windows. +- An Edge host that has already been prepared for installation. + +### Procedure + +1. Create a file named `user-data`, and include the following content. Replace `network-name` and `network-password` + with the name and password of your Wifi network. + + ```yaml + #cloud-config + install: + bind_mounts: + - /var/lib/wpa + + stages: + network.before: + - name: "Connect to Wi-Fi" + commands: + - | + # Find the first wireless network interface + wireless_interface="" + for interface in $(ip link | grep -oP '^\d+: \K[^:]+(?=:)') + do + if [ -d "/sys/class/net/$interface/wireless" ]; then + wireless_interface=$interface + break + fi + done + + # Check if a wireless interface was found and connect it to WiFi + if [ -n "$wireless_interface" ]; then + wpa_passphrase network-name network-password | tee /var/lib/wpa/wpa_supplicant.conf + wpa_supplicant -B -c /var/lib/wpa/wpa_supplicant.conf -i $wireless_interface + dhclient $wireless_interface + else + echo "No wireless network interface found." + fi + ``` + +2. Follow the rest of the steps in the [Apply Site User Data](../site-deployment/site-installation/site-user-data.md) + section. + +### Validate + +1. Power up the Edge host and wait for it to boot to the registration screen. Do not connect the Edge host with a wired + connection. +2. In the **Default Address** field, confirm that the Edge host has an IP address. This means the Edge host is connected + to a network. Since you did not connect the Edge host with a wired connection, this means that the Edge host has + successfully connected to your wireless network and received an IP address. diff --git a/docs/docs-content/clusters/edge/networking/networking.md b/docs/docs-content/clusters/edge/networking/networking.md index 6362bcd835..b0eb37f52f 100644 --- a/docs/docs-content/clusters/edge/networking/networking.md +++ b/docs/docs-content/clusters/edge/networking/networking.md @@ -20,3 +20,4 @@ ensure that you can keep your Edge clusters and their services operational and a - [Publish Cluster Services with Kube-vip](kubevip.md) - [Enable Overlay Network](vxlan-overlay.md) - [Enable Local Harbor Image Registry](local-registry.md) +- [Connect Intel NUC Edge Host to Wifi](./connect-wifi.md) diff --git a/docs/docs-content/clusters/edge/site-deployment/site-installation/site-user-data.md b/docs/docs-content/clusters/edge/site-deployment/site-installation/site-user-data.md index a1f1b3473b..9c7d1c34d3 100644 --- a/docs/docs-content/clusters/edge/site-deployment/site-installation/site-user-data.md +++ b/docs/docs-content/clusters/edge/site-deployment/site-installation/site-user-data.md @@ -20,45 +20,83 @@ to a bootable device, such as a USB stick. - `mkisofs`, or `genisoimage`, or similar ISO management software. -- `cdrtools` or `wodim` for Windows. + - `cdrtools` or `wodim` for Windows. ## Create ISO -1. Create a file called **user-data** that contains the additional configurations you want to override or inject. +1. Create a file called **user-data** that contains the additional configurations you want to override or inject. + Ensure that the file starts with a line that only contains `#cloud-config`. Only include configurations you'd like + to add or override. There is no need to include user data that was already present when the ISO image was build in + the [Build Edge Artifacts](../../edgeforge-workflow/palette-canvos.md) step. -
+ ```shell + touch user-data + ``` -```shell -touch user-data -``` + For example, you can include the following content in the **user-data** file to connect your Edge host to Wi-Fi. + This requires wpa_supplicant to be included in your base OS image. For more information, refer to + [Connect Intel NUC Edge Host to Wifi](../../networking/connect-wifi.md). -2. Create an empty **meta-data** file: + ```yaml + #cloud-config + install: + bind_mounts: + - /var/lib/wpa -
+ stages: + network.before: + - name: "Connect to wifi" + commands: + - | + # Find the first wireless network interface + wireless_interface="" + for interface in $(ip link | grep -oP '^\d+: \K[^:]+(?=:)') + do + if [ -d "/sys/class/net/$interface/wireless" ]; then + wireless_interface=$interface + break + fi + done -```shell -touch meta-data -``` + # Check if a wireless interface was found and connect it to WiFi + if [ -n "$wireless_interface" ]; then + wpa_passphrase Madrid supersup | tee /var/lib/wpa/wpa_supplicant.conf + wpa_supplicant -B -c /var/lib/wpa/wpa_supplicant.conf -i $wireless_interface + dhclient $wireless_interface + else + echo "No wireless network interface found." + fi + ``` -3. Create an ISO using the following command. +2. Create an empty **meta-data** file: -MacOS/Linux: + ```shell + touch meta-data + ``` -```shell -mkisofs -output site-user-data.iso -volid cidata -joliet -rock user-data meta-data -``` +3. Create an ISO using the following command. -Windows: + + -```shell -genisoimage -output site-user-data.iso -volid cidata -joliet -rock user-data meta-data -``` + ```shell + mkisofs -output site-user-data.iso -volid cidata -joliet -rock user-data meta-data + ``` -This generates an ISO file called site-user-data.iso in the current directory.
+ -4. Copy the ISO to a bootable device such as a USB drive. + -
+ ```shell + genisoimage -output site-user-data.iso -volid cidata -joliet -rock user-data meta-data + ``` + + + + +This generates an ISO file called **site-user-data.iso** in the current directory. + +4. Flash your bootable device such as a USB drive with the ISO file you just created. :::info @@ -72,13 +110,16 @@ This generates an ISO file called site-user-data.iso in the current directory. < 5. Once the Edge host arrives at the physical site. Load the USB drive to the Edge host before powering it on. The Edge Installer will apply the new user data during the installation process. -
- ## Validate You can validate that the ISO image is not corrupted by attempting to flash a bootable device. Most software that creates a bootable device will validate the ISO image before the flash process. +If you have SSH access, you can also SSH into the Edge host and locate your **user-data** file in either `/oem` or +`/run/stylus`. The site-specific user data is named **user-data** while the original user data file is named something +similar to `90_custom.yaml`. If you can find the files on the Edge host, it means the user data has been applied +successfully. + ## Next Steps Before you register your Edge host with Palette you must have a tenant registration token. Review the diff --git a/vale/styles/Vocab/Internal/accept.txt b/vale/styles/Vocab/Internal/accept.txt index f4219c21c2..723dba41f0 100644 --- a/vale/styles/Vocab/Internal/accept.txt +++ b/vale/styles/Vocab/Internal/accept.txt @@ -183,3 +183,4 @@ untrusted goroutines renegotiation renegotiations +wpa_supplicant \ No newline at end of file