diff --git a/docs/install-upgrade/build-wiring.md b/docs/install-upgrade/build-wiring.md index 47743c4..ec983d9 100644 --- a/docs/install-upgrade/build-wiring.md +++ b/docs/install-upgrade/build-wiring.md @@ -3,36 +3,26 @@ !!! warning "" Under construction. -You can find mode details in the User Guide including [switch features and port naming](../user-guide/profiles.md). It's -mandatoy to for all switches to reference a `SwitchProfile` in the `spec.profile` of the `Switch` object. Only port -naming defined by switch profiles could be used in the wiring diagram, NOS (or any other) port names aren't supported. +You can find more details in the User Guide including [switch features and port naming](../user-guide/profiles.md). It's mandatoy to for all switches to reference a `SwitchProfile` in the `spec.profile` of the `Switch` object. Only port naming defined by switch profiles could be used in the wiring diagram, NOS (or any other) port names aren't supported. In the meantime, to have a look at working wiring diagram for Hedgehog Fabric, run the sample generator that produces VLAB-compatible wiring diagrams: ```console -ubuntu@sl-dev:~$ hhfab wiring sample -h +ubuntu@sl-dev:~$ hhfab sample -h + NAME: - hhfab wiring sample - sample wiring diagram (would work for vlab) + hhfab sample - generate sample wiring diagram USAGE: - hhfab wiring sample [command options] [arguments...] + hhfab sample command [command options] + +COMMANDS: + spine-leaf, sl generate sample spine-leaf wiring diagram + collapsed-core, cc generate sample collapsed-core wiring diagram + help, h Shows a list of commands or help for one command OPTIONS: - --brief, -b brief output (only warn and error) (default: false) - --fabric-mode value, -m value fabric mode (one of: collapsed-core, spine-leaf) (default: "spine-leaf") - --help, -h show help - --verbose, -v verbose output (includes debug) (default: false) - - wiring generator options: - - --chain-control-link chain control links instead of all switches directly connected to control node if fabric mode is spine-leaf (default: false) - --control-links-count value number of control links if chain-control-link is enabled (default: 0) - --fabric-links-count value number of fabric links if fabric mode is spine-leaf (default: 0) - --mclag-leafs-count value number of mclag leafs (should be even) (default: 0) - --mclag-peer-links value number of mclag peer links for each mclag leaf (default: 0) - --mclag-session-links value number of mclag session links for each mclag leaf (default: 0) - --orphan-leafs-count value number of orphan leafs (default: 0) - --spines-count value number of spines if fabric mode is spine-leaf (default: 0) - --vpc-loopbacks value number of vpc loopbacks for each switch (default: 0) + --help, -h show help ``` + diff --git a/docs/install-upgrade/overview.md b/docs/install-upgrade/overview.md index 6177b36..c2111dc 100644 --- a/docs/install-upgrade/overview.md +++ b/docs/install-upgrade/overview.md @@ -5,159 +5,82 @@ ## Prerequisites -* Have a machine with access to the Internet to use Fabricator and build installer -* Have a machine to install Fabric Control Node on with enough NICs to connect to at least one switch using Front Panel - ports and enough CPU and RAM (see [System Requirements](./requirements.md)) as well as IPMI access to it to install - the OS +* A machine with access to the Internet to use Fabricator and build installer +* An 8 GB USB flash drive, if you are not using virtual media +* Have a machine to function as the Fabric Control Node.[System Requirements](./requirements.md)) as well as IPMI access to it to install + the OS. +* Have a management switch with at least 1 10GbE port * Have enough [Supported Switches](./supported-devices.md) for your Fabric -## Main steps +## Overview of Install Process -This chapter is dedicated to the Hedgehog Fabric installation on bare-metal control node(s) and switches, their -preparation and configuration. +This section is dedicated to the Hedgehog Fabric installation on bare-metal control node(s) and switches, their +preparation and configuration. To install the vlab see [Vlab Overivew](../vlab/overview.md). -Get `hhfab` installed following instructions from the [Download](../getting-started/download.md) section. +Download and install `hhfab` following instructions from the [Download](../getting-started/download.md) section. The main steps to install Fabric are: 1. Install `hhfab` on the machines with access to the Internet 1. [Prepare Wiring Diagram](./build-wiring.md) - 1. [Select Fabric Configuration](./config.md) + 1. [Select Fabric Configuration](./config.md) // TODO - section on dhcp or ntp servers, the FAB.yaml 1. [Build Control Node configuration and installer](#build-control-node-configuration-and-installer) 1. [Install Control Node](#install-control-node) - 1. Install Flatcar Linux on the Control Node - 1. Upload and run Control Node installer on the Control Node + 1. Insert USB with control-os image into Fabric Control Node + 1. Boot the node off the USB to initiate the installation +1. Prepare Management Network + 1. Connect switch to Fabric control node + 1. Connect 1GbE Management ports of switches to control switch 1. Prepare supported switches - 1. [Install Hedgehog ONIE (HONIE) on them](./onie-update.md) - 1. Reboot them into ONIE Install Mode to have them automatically provisioned + 1. Boot them into ONIE Install Mode to have them automatically provisioned ## Build Control Node configuration and installer -It's the only step that requires Internet access, to download artifacts and build the installer. +### HHFAB commands +- `hhfab init --wiring wiring-lab.yaml` +- edit the `fab.yaml` file for your needs +- `hhfab validate` +- `hhfab build` -Once you've prepared the Wiring Diagram, initialize Fabricator by running `hhfab init` command and passing optional -configuration into it as well as wiring diagram file(s) as flags. Additionally, there are a lot of customizations -available as flags, e.g. to setup default credentials, keys and etc. For more details on the command invocation, -refer to `hhfab init --help`. - -The `--dev` option activates the development mode which enables default credentials and keys for the Control -Node and switches: - -* Default user with passwordless sudo for the Control Node and test servers is `core` with password `HHFab.Admin!`. -* Admin user with full access and passwordless sudo for the switches is `admin` with password `HHFab.Admin!`. -* Read-only, non-sudo user with access only to the switch CLI for the switches is `op` with password `HHFab.Op!`. - -Alternatively, you can pass your own credentials and keys using `--authorized-key` and `--control-password-hash` flags. -Generate a password hash with command `openssl passwd -5`. Further customization items are available in the config -file and can be passed using the `--config` flag. - -```bash -hhfab init --preset lab --dev --wiring file1.yaml --wiring file2.yaml -hhfab build -``` - -As a result, you will get the following files in the `.hhfab` directory or the one you've passed using `--basedir` flag: - -* `control-os/ignition.json` - ignition config for the Control Node to get OS installed -* `control-install.tgz` - installer for the Control Node, it will be uploaded to the Control Node and run there +### Burn USB image to disk +!!! warning "" + This will erase data on the usb disk. +- Insert the usb to your machine +- Identify the path to your usb stick for example `/dev/sdc` +- Issue the command to write the image to the usb drive + - `sudo dd if=/path/to/control-os/img of=/dev/sdc bs=4k status=progress` +There are utilities that assist this process such as [etcher](https://etcher.balena.io/). -More details on configuring the Fabric are available in the [Configuration](./config.md) section. +TODO - details on what comes out of each step +TODO - go to the config page to talk about the options inside the fab.yaml ## Install Control Node -### Connected Instructions This control node should be given a static IP address. Either a lease or statically assigned. -1. Download the [latest stable Flatcar Container Linux ISO ~400MiB][Flatcar ISO] - -[Flatcar ISO]: https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_iso_image.iso - -1. Bios boot the control node using the ISO, via virtual media, USB, or other way. - -1. Once the control node has booted it will auto login to a shell - -1. Upload the file `ignition.json` built during the previous step to the -system and run the Flatcar installation: - -```bash -sudo flatcar-install -d /dev/sda -i ignition.json -``` - -Where `/dev/sda` is a disk you want to install Control Node to and `ignition.json` is the `control-os/ignition.json` -file from previous step uploaded to the Flatcar installer. This installer reaches out to the publically available images to download, verify and install flatcar to the given disk. - -The installation is finished when you see a message similar to the following: - -```shell -Installing Ignition config ignition.json... -Success! Flatcar Container Linux stable 3510.2.6 is installed on /dev/sda -``` - -[Move on to the next step](#install-hedgehog-controller) - -### Air Gapped Instructions -Control Node installation is fully air-gapped and doesn't require Internet access. A static IP is still needed as command and control communications between the switches and controller use IP. The instructions are similar to above. - -1. Download the [latest stable Flatcar Container Linux ISO ~400MiB][Flatcar ISO] and bios boot into it (using IPMI attaching media, USB -stick or any other way). - -[Flatcar ISO]: https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_iso_image.iso - -1. Download the [latest stable Flatcar Container Linux Image ~500MiB][Flatcar Image] and copy that file to media that can be attached to the control node. -[Flatcar Image]: https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_image.bin.bz2 - -1. Copy the `control-os/ignition.json` file to the media from the above step. - -1. Bios boot the control node using the iso from above. - -1. Once the control node has booted, it will auto-login to a shell. - -1. Attach the media containing both the container image file and the ignition file to the booted control node. - -1. Uncompress the image `bunzip -d ./path/to/flatcar_production_image.bin.bz2`, if you want to keep the compressed image use the `-k` flag. - -```bash -sudo flatcar-install -d /dev/sda -i ignition.json -f flatcar_production_image.bin -``` - -Where `/dev/sda` is a disk you want to install Control Node to and `ignition.json` is the `control-os/ignition.json` -file from previous step uploaded to the Flatcar installer. By providing an image to the installer, no public internet connections will be attemtped. +1. Configure the server to use UEFI boot without secure boot -The installation is finished when you see a message similar to the following: +1. Attach the image to the server either by inserting via USB, or attaching via virtual media. After this step the process is automated -```shell -Installing Ignition config ignition.json... -Success! Flatcar Container Linux stable 3510.2.6 is installed on /dev/sda -``` -[Move on to the next step](#install-hedgehog-controller) +1. Once the control node has booted it will auto login and begin the installation process + 1. Optionally use ` journalctl -f -u flatcar-install.service` to monitor progress -### Install HedgeHog Controller +1. Once the install is complete the system will automatically reboot -Once the installation is finished, reboot the machine and wait for it to boot into the installed Flatcar Linux. +1. Upon booting into the freshly installed system, the fabric installation will automatically begin + 1. Optionally this can be monitored with `journalctl -f -u fabric-install.service` -At that point, you should get into the installed Flatcar Linux using the dev or provided credentials with user `core` -and you can now install Hedgehog Open Network Fabric on it. Download `control-install.tgz` to the just installed Control -Node (for example, by using scp) and run it. +1. The install is complete when the log emits "Control Node installation complete" + 1. Additionally the systemctl status will show `inactive (dead)` indicating that the executable has finished -```bash -tar xzf control-install.tgz && cd control-install && sudo ./hhfab-recipe run -``` -The command prints the logs generated while installing Fabric (including logs from the Kubernetes cluster, miscellaneous -OCI registry misc components, and more). At the end, you should observe lines similar to the following: +[Move on to the next step](#fabric-manages-switches) -``` -... -01:34:45 INF Running name=reloader-image op="push fabricator/reloader:v1.0.40" -01:34:47 INF Running name=reloader-chart op="push fabricator/charts/reloader:1.0.40" -01:34:47 INF Running name=reloader-install op="file /var/lib/rancher/k3s/server/manifests/hh-reloader-install.yaml" -01:34:47 INF Running name=reloader-wait op="wait deployment/reloader-reloader" -deployment.apps/reloader-reloader condition met -01:35:15 INF Done took=3m39.586394608s -``` +### Fabric Manages Switches -At that point, you can start interacting with the Fabric using `kubectl`, `kubectl fabric` and `k9s`, all preinstalled -as part of the Control Node installer. +Now that the install has finished, you can start interacting with the Fabric using `kubectl`, `kubectl fabric` and `k9s`, all preinstalled as part of the Control Node installer. -You can now get HONIE installed on your switches and reboot them into ONIE Install Mode to have them automatically -provisioned from the Control Node. +Now the fabric is handing out dhcp addresses to the switches via the management network. Optionally, to monitor this process: +- enter `k9s` at the command prompt +- use the arror keys to select the boot pod TODO (use the specific name) +- the logs of the pod will be displayed diff --git a/docs/install-upgrade/requirements.md b/docs/install-upgrade/requirements.md index 02ffa9a..e0b2b73 100644 --- a/docs/install-upgrade/requirements.md +++ b/docs/install-upgrade/requirements.md @@ -2,6 +2,7 @@ - Fast SSDs for system/root as well as Kubernetes and container runtime folders are required for stable work - SSDs are mandatory for Control Nodes +- 10 GbE port for connection to management network - Minimal (non-HA) setup is a single Control Node - (Future) Full (HA) setup is at least 3 Control Nodes - (Future) Extra nodes could be used for things like Logging, Monitoring, Alerting stack, and more