Skip to content

Commit

Permalink
initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
@mrbojangles3
mrbojangles3 committed Oct 17, 2024
1 parent 4065c95 commit d485ea3
Show file tree
Hide file tree
Showing 3 changed files with 60 additions and 146 deletions.
34 changes: 12 additions & 22 deletions docs/install-upgrade/build-wiring.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

171 changes: 47 additions & 124 deletions docs/install-upgrade/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
1 change: 1 addition & 0 deletions docs/install-upgrade/requirements.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit d485ea3

Please sign in to comment.