From cb344363f315f054ca854fb11f17fcc4678ae455 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Mon, 16 Dec 2024 16:00:34 -0500 Subject: [PATCH 1/7] add iso related options, macos instructions, attempted diagram of control node architecure --- docs/install-upgrade/install.md | 47 ++++++++++++++++++++++++++++++--- 1 file changed, 43 insertions(+), 4 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index ac8aea0..a6714db 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -41,19 +41,29 @@ Hedgehog has created a command line utility, called `hhfab`, that helps generate 1. The `init` command generates a `fab.yaml` file, edit the `fab.yaml` file for your needs 1. ensure the correct boot disk (e.g. `/dev/sda`) and control node NIC names are supplied 1. `hhfab validate` -1. `hhfab build` +1. `hhfab build --mode iso` + 1. There are two options for the format of the bootable media. ISO and IMG. An ISO is best suited to use with IPMI based virtual media. The img file is designed for writing to a removable USB drive. -The installer for the fabric is generated in `$CWD/result/`. This installation image is named `control-1-install-usb.img` and is 7.5 GB in size. Once the image is created, you can write it to a USB drive, or mount it via virtual media. +The installer for the fabric is generated in `$CWD/result/`. This installation image is named `control-1-install-usb.iso` and is 7.5 GB in size. Once the image is created, you can write it to a USB drive, or mount it via virtual media. ### Write USB Image to Disk !!! warning "" This will erase data on the USB disk. +### Steps for Linux 1. Insert the USB to your machine 1. Identify the path to your USB stick, for example: `/dev/sdc` 1. Issue the command to write the image to the USB drive - - `sudo dd if=control-1-install-usb.img of=/dev/sdc bs=4k status=progress` + - `sudo dd if=control-1-install-usb.iso of=/dev/sdc bs=4k status=progress` + +### Steps for MacOS +1. Plug the drive into the computer +1. Open the terminal +1. Identify the drive using `diskutil list` +1. Unmount the disk `diskutil unmount disk5`, the disk is specific to your environment +1. Write the image to the disk: `sudo dd if=./control-1-install-usb.iso of=/dev/disk5 bs=4k status=progress` + There are utilities that assist this process such as [etcher](https://etcher.balena.io/). @@ -84,7 +94,36 @@ This control node should be given a static IP address. Either a lease or statica ### Configure Management Network -The control node is dual-homed. It has a 10GbE interface that connects to the management network. The other link called `external` in the `fab.yaml` file is for the customer to access the control node. The management network is for the command and control of the switches that comprise the fabric. This management network can be a simple broadcast domain with layer 2 connectivity. The control node will run a DHCP and small http servers. The management network is not accessible to machines or devices not associated with the fabric. +The control node is dual-homed. It has a 10GbE interface that connects to the management network. The other link called `external` in the `fab.yaml` file is for the customer to access the control node via their building IT network. The management network is for the command and control of the switches that comprise the fabric. This management network can be a simple broadcast domain with layer 2 connectivity. The control node will run a DHCP and small http servers. The management network is not accessible to machines or devices not associated with the fabric. The following diagram illustrates 3 networks for the control node. A "Local IT" network that is used for command and control or IPMI. The other network is exclusive to Hedgehog, the best solution is a dedicated network switch, but a private exclusive vlan is potentially workable. +```mermaid +graph LR + +N1[IPMI] +N2[SSH access to Operating system] +N3[HH Exclusive Network] +C1[Control Node] +S1([Spine 1]) +S2([Spine 1]) +L1([Leaf 1]) +L2([Leaf 2]) +L3([Leaf 3]) +L4([Leaf 4]) + +subgraph itnet [Local IT Network] +N1 <--> C1 +N2 <--> C1 +end + +subgraph hhnet [HH Network Mangement] +C1 <--> N3 +end + +S1 & S2 <--> L1 & L2 & L3 & L4 + +hhnet <--> S1 & S2 & L1 & L2 & L3 & L4 + +``` + ### Fabric Manages Switches From 825a2828e7b200a5e185045b77797d6815369641 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Tue, 17 Dec 2024 11:42:57 -0500 Subject: [PATCH 2/7] changes due to feedback --- docs/install-upgrade/install.md | 49 +++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index a6714db..e9fb438 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -33,7 +33,13 @@ The main steps to install Fabric are: 1. Boot them into ONIE Install Mode to have them automatically provisioned ## Build Control Node configuration and Installer -Hedgehog has created a command line utility, called `hhfab`, that helps generate the wiring diagram and fabric configuration, validate the supplied configurations, and generate an installation image (.img) suitable for writing to a USB flash drive or mounting via IPMI virtual media. The first `hhfab` command to run is `hhfab init`. This will generate the main configuration file, `fab.yaml`. `fab.yaml` is responsible for almost every configuration of the fabric with the exception of the wiring. Each command and subcommand have usage messages, simply supply the `-h` flag to your command or sub command to see the available options. For example `hhfab vlab -h` and `hhfab vlab gen -h`. +Hedgehog has created a command line utility, called `hhfab`, that helps generate the wiring diagram and fabric configuration, +validate the supplied configurations, and generate an installation image (.img or .iso) suitable +for writing to a USB flash drive or mounting via IPMI virtual media. The first `hhfab` command to +run is `hhfab init`. This will generate the main configuration file, `fab.yaml`. `fab.yaml` is +responsible for almost every configuration of the fabric with the exception of the wiring. Each +command and subcommand have usage messages, simply supply the `-h` flag to your command or sub +command to see the available options. For example `hhfab vlab -h` and `hhfab vlab gen -h`. ### HHFAB commands to make a bootable image @@ -42,7 +48,8 @@ Hedgehog has created a command line utility, called `hhfab`, that helps generate 1. ensure the correct boot disk (e.g. `/dev/sda`) and control node NIC names are supplied 1. `hhfab validate` 1. `hhfab build --mode iso` - 1. There are two options for the format of the bootable media. ISO and IMG. An ISO is best suited to use with IPMI based virtual media. The img file is designed for writing to a removable USB drive. + 1. There are two options for the format of the bootable media: ISO and USB. An ISO is best suited to use with IPMI based + virtual media. The USB file is designed for writing to a removable USB drive. USB is the default. The installer for the fabric is generated in `$CWD/result/`. This installation image is named `control-1-install-usb.iso` and is 7.5 GB in size. Once the image is created, you can write it to a USB drive, or mount it via virtual media. @@ -55,14 +62,14 @@ The installer for the fabric is generated in `$CWD/result/`. This installation i 1. Insert the USB to your machine 1. Identify the path to your USB stick, for example: `/dev/sdc` 1. Issue the command to write the image to the USB drive - - `sudo dd if=control-1-install-usb.iso of=/dev/sdc bs=4k status=progress` + - `sudo dd if=control-1-install-usb.img of=/dev/sdc bs=4k status=progress` ### Steps for MacOS 1. Plug the drive into the computer 1. Open the terminal 1. Identify the drive using `diskutil list` 1. Unmount the disk `diskutil unmount disk5`, the disk is specific to your environment -1. Write the image to the disk: `sudo dd if=./control-1-install-usb.iso of=/dev/disk5 bs=4k status=progress` +1. Write the image to the disk: `sudo dd if=./control-1-install-usb.img of=/dev/disk5 bs=4k status=progress` There are utilities that assist this process such as [etcher](https://etcher.balena.io/). @@ -94,14 +101,20 @@ This control node should be given a static IP address. Either a lease or statica ### Configure Management Network -The control node is dual-homed. It has a 10GbE interface that connects to the management network. The other link called `external` in the `fab.yaml` file is for the customer to access the control node via their building IT network. The management network is for the command and control of the switches that comprise the fabric. This management network can be a simple broadcast domain with layer 2 connectivity. The control node will run a DHCP and small http servers. The management network is not accessible to machines or devices not associated with the fabric. The following diagram illustrates 3 networks for the control node. A "Local IT" network that is used for command and control or IPMI. The other network is exclusive to Hedgehog, the best solution is a dedicated network switch, but a private exclusive vlan is potentially workable. +The control node is dual-homed. It has a 10GbE interface that connects to the management network. +The other link called `external` in the `fab.yaml` file is for the customer to access the control +node via their local IT network. The management network is for the command and control of the +switches that comprise the fabric. The management network can be a simple broadcast domain with +layer 2 connectivity. The control node will run a DHCP and a small http server. The management +network is not accessible to machines or devices not associated with the fabric. The following +diagram illustrates 3 network connections for the control node. A "Local IT" network that is used +for IPMI and ssh access to the control node operating system. The other network is exclusive to +the control node, the best solution is a dedicated network switch, but a private exclusive vlan is +potentially workable. + ```mermaid -graph LR +flowchart LR -N1[IPMI] -N2[SSH access to Operating system] -N3[HH Exclusive Network] -C1[Control Node] S1([Spine 1]) S2([Spine 1]) L1([Leaf 1]) @@ -109,22 +122,24 @@ L2([Leaf 2]) L3([Leaf 3]) L4([Leaf 4]) -subgraph itnet [Local IT Network] -N1 <--> C1 -N2 <--> C1 +subgraph ctrlnet [Fabric Control Network] + C1[Control Node] end -subgraph hhnet [HH Network Mangement] -C1 <--> N3 +subgraph localnet [Local IT Network] + N1[IPMI] + N2[SSH access to operating system] + N1 <--> C1 + N2 <--> C1 end + S1 & S2 <--> L1 & L2 & L3 & L4 -hhnet <--> S1 & S2 & L1 & L2 & L3 & L4 +ctrlnet <-..-> S1 & S2 & L1 & L2 & L3 & L4 ``` - ### Fabric Manages Switches Now that the install has finished, you can start interacting with the Fabric using `kubectl`, `kubectl fabric` and `k9s`, all pre-installed as part of the Control Node installer. From 292aa08498bd48c5250f0aaf42a789d0e3c383bf Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Tue, 17 Dec 2024 17:04:51 -0500 Subject: [PATCH 3/7] last minute change --- docs/install-upgrade/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index e9fb438..3dd02cf 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -49,7 +49,7 @@ command to see the available options. For example `hhfab vlab -h` and `hhfab vla 1. `hhfab validate` 1. `hhfab build --mode iso` 1. There are two options for the format of the bootable media: ISO and USB. An ISO is best suited to use with IPMI based - virtual media. The USB file is designed for writing to a removable USB drive. USB is the default. + virtual media. The USB file is designed for writing to a removable USB drive. ISO is the default. The installer for the fabric is generated in `$CWD/result/`. This installation image is named `control-1-install-usb.iso` and is 7.5 GB in size. Once the image is created, you can write it to a USB drive, or mount it via virtual media. From 093408c6b7bc66dbbc6b6746262a2136845d0d96 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 18 Dec 2024 06:54:30 -0500 Subject: [PATCH 4/7] remove confusing diagram, clean up prose --- docs/install-upgrade/install.md | 43 ++++++--------------------------- 1 file changed, 8 insertions(+), 35 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index 3dd02cf..1ea4137 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -101,44 +101,17 @@ This control node should be given a static IP address. Either a lease or statica ### Configure Management Network -The control node is dual-homed. It has a 10GbE interface that connects to the management network. -The other link called `external` in the `fab.yaml` file is for the customer to access the control -node via their local IT network. The management network is for the command and control of the +The control node is dual-homed. It has a 10GbE interface that connects to the management network +of the switches that comprise the fabric called `mangement` in the `fab.yam called `mangement` in the + `fab.yamll. The other link called `external` in the `fab.yaml` file is for the customer to access + the control node via their local IT network. The management network is for the command and control of the switches that comprise the fabric. The management network can be a simple broadcast domain with layer 2 connectivity. The control node will run a DHCP and a small http server. The management -network is not accessible to machines or devices not associated with the fabric. The following -diagram illustrates 3 network connections for the control node. A "Local IT" network that is used -for IPMI and ssh access to the control node operating system. The other network is exclusive to -the control node, the best solution is a dedicated network switch, but a private exclusive vlan is -potentially workable. +network is not accessible to machines or devices not associated with the fabric, it is a private, +exclusive network. -```mermaid -flowchart LR - -S1([Spine 1]) -S2([Spine 1]) -L1([Leaf 1]) -L2([Leaf 2]) -L3([Leaf 3]) -L4([Leaf 4]) - -subgraph ctrlnet [Fabric Control Network] - C1[Control Node] -end - -subgraph localnet [Local IT Network] - N1[IPMI] - N2[SSH access to operating system] - N1 <--> C1 - N2 <--> C1 -end - - -S1 & S2 <--> L1 & L2 & L3 & L4 - -ctrlnet <-..-> S1 & S2 & L1 & L2 & L3 & L4 - -``` +The `external` network is meant to give ssh access to the host operating system for +for ssh access to the control node operating system. ### Fabric Manages Switches From 2531f0003827fb984ce1d60561304f4e6466b766 Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 18 Dec 2024 09:35:53 -0500 Subject: [PATCH 5/7] Good clarity from edipascale --- docs/install-upgrade/install.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index 1ea4137..e629ca5 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -101,17 +101,15 @@ This control node should be given a static IP address. Either a lease or statica ### Configure Management Network -The control node is dual-homed. It has a 10GbE interface that connects to the management network -of the switches that comprise the fabric called `mangement` in the `fab.yam called `mangement` in the - `fab.yamll. The other link called `external` in the `fab.yaml` file is for the customer to access - the control node via their local IT network. The management network is for the command and control of the -switches that comprise the fabric. The management network can be a simple broadcast domain with -layer 2 connectivity. The control node will run a DHCP and a small http server. The management -network is not accessible to machines or devices not associated with the fabric, it is a private, -exclusive network. - -The `external` network is meant to give ssh access to the host operating system for -for ssh access to the control node operating system. +The control node is dual-homed; the two networks it connects to are called respectively `management` +and `external` in the `fab.yaml` file. +The `management` network is for the command and control of the switches that comprise the fabric. It +can be a simple broadcast domain with layer 2 connectivity. The management network is not accessible +to machines or devices not associated with the fabric; it is a private, exclusive network. The control +node has a 10GbE interface that connects to the management network, and it runs a DHCP and a small http +server. +The `external` network on the other hand is for the customer to access the control node via their local +IT network. It is meant to give ssh access to the control node host operating system. ### Fabric Manages Switches From 11ec3be1b25c2be9e3a7a470f010d2d7636ffc7d Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 18 Dec 2024 20:19:41 -0500 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Quentin Monnet --- docs/install-upgrade/install.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index e629ca5..54f1d7f 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -101,15 +101,16 @@ This control node should be given a static IP address. Either a lease or statica ### Configure Management Network -The control node is dual-homed; the two networks it connects to are called respectively `management` -and `external` in the `fab.yaml` file. -The `management` network is for the command and control of the switches that comprise the fabric. It -can be a simple broadcast domain with layer 2 connectivity. The management network is not accessible -to machines or devices not associated with the fabric; it is a private, exclusive network. The control -node has a 10GbE interface that connects to the management network, and it runs a DHCP and a small http -server. -The `external` network on the other hand is for the customer to access the control node via their local -IT network. It is meant to give ssh access to the control node host operating system. +The control node is dual-homed: it connects to two different networks, which are called +`management` and `external`, respectively, in the `fab.yaml` file. +The `management` network is for controlling the switches that comprise the fabric. It +can be a simple broadcast domain with layer 2 connectivity. The management network is +not accessible to machines or devices not associated with the fabric; it is a private, +exclusive network. The control node connects to the management network via a 10 GbE +interface. It runs a DHCP server, as well as a small HTTP server. + +The `external` network allows the user to access the control node via their local +IT network. It provides SSH access to the host operating system on the control node. ### Fabric Manages Switches From e8950217f65351948b519c854d9896bd7cf5e08d Mon Sep 17 00:00:00 2001 From: Logan Blyth Date: Wed, 18 Dec 2024 20:34:41 -0500 Subject: [PATCH 7/7] rephrasing for clarity...hopefully --- docs/install-upgrade/install.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/install-upgrade/install.md b/docs/install-upgrade/install.md index 54f1d7f..4638d13 100644 --- a/docs/install-upgrade/install.md +++ b/docs/install-upgrade/install.md @@ -48,8 +48,7 @@ command to see the available options. For example `hhfab vlab -h` and `hhfab vla 1. ensure the correct boot disk (e.g. `/dev/sda`) and control node NIC names are supplied 1. `hhfab validate` 1. `hhfab build --mode iso` - 1. There are two options for the format of the bootable media: ISO and USB. An ISO is best suited to use with IPMI based - virtual media. The USB file is designed for writing to a removable USB drive. ISO is the default. + 1. An ISO is best suited to use with IPMI based virtual media. If desired an IMG file suitable for writing to a USB drive, can be created by passing the `--mode usb` option. ISO is the default. The installer for the fabric is generated in `$CWD/result/`. This installation image is named `control-1-install-usb.iso` and is 7.5 GB in size. Once the image is created, you can write it to a USB drive, or mount it via virtual media.