incremental commit

githedgehog · Oct 18, 2024 · 0ea7756 · 0ea7756
1 parent d485ea3
commit 0ea7756
Show file tree

Hide file tree

Showing 2 changed files with 74 additions and 55 deletions.
diff --git a/docs/install-upgrade/config.md b/docs/install-upgrade/config.md
@@ -9,22 +9,35 @@
     use of on-demand DHCP for multiple IPv4/VLAN namespaces and overlapping IP ranges, and it adds DHCP leases
     into the Fabric API
 
+```yaml
+spec:
+    config
+    ...
+        fabric:
+          mode: spine-leaf
+          includeONIE: true
+
+```
+
 For more information about how to use `hhfab init`, run `hhfab init --help`.
 
 ## Configure switch users
 
-It's currently only possible by using a config yaml file for the `hhfab init -c <config-file.yaml>` command. You can
+It's currently only possible by using a yaml configuration file for the `hhfab init -c <config-file.yaml>` command. You can
 specify users to be configured on the switches in the following format:
 
 ```yaml
-config:
+spec:
+    config
     ...
-    fabric:
+        fabric:
         ...
-        switchUsers:
-          - name: test
+        defaultSwitchUsers:
+            admin:
+            role: admin
             password: $5$oj/NxDtFw3eTyini$VHwdjWXSNYRxlFMu.1S5ZlGJbUF/CGmCAZIBroJlax4
-            role: operator
+            authorizedKeys:
+              - "ssh-ed25519 THISisAkeYFOrSShiNGtoHoSTs"
 ```
 
 Where `name` is the username, `password` is the password hash created with `openssl passwd -5` command, and `role` is
@@ -40,45 +53,44 @@ access the configured targets. It could be done by passing `--control-proxy=true
 Metrics includes port speeds, counters, errors, operational status, transceivers, fans, power supplies, temperature
 sensors, BGP neighbors, LLDP neighbors, and more. Logs include agent logs.
 
-Configuring the exporters and targets is currently only possible by using a config yaml file for the
+Configuring the exporters and targets is currently only possible by using a yaml configuration file for the
 `hhfab init -c <config-file.yaml>` command using the following format:
 
 ```yaml
-config:
-    ...
-    fabric:
-        ...
+spec:
+  config:
+      ...
+      defaultAlloyConfig:
+        agentScrapeIntervalSeconds: 120
+        unixScrapeIntervalSeconds: 120
+        unixExporterEnabled: true
         controlProxy: true # (optional) same as passing --control-proxy=true to hhfab init
-        alloy:
-            agentScrapeIntervalSeconds: 120
-            controlProxyURL: http://172.30.1.1:31028
-            lokiTargets:
-                grafana_cloud: # target name, multiple targets can be configured
-                    basicAuth: # optional
-                        password: "<password>"
-                        username: "<username>"
-                    labels: # labels to be added to all logs
-                        env: env-1
-                    url: https://logs-prod-021.grafana.net/loki/api/v1/push
-                    useControlProxy: true # if the Loki API is not available from the switches directly, use the Control Node as a proxy
-            prometheusTargets:
-                grafana_cloud: # target name, multiple targets can be configured
-                    basicAuth: # optional
-                        password: "<password>"
-                        username: "<username>"
-                    labels: # labels to be added to all metrics
-                        env: env-1
-                    sendIntervalSeconds: 120
-                    url: https://prometheus-prod-36-prod-us-west-0.grafana.net/api/prom/push
-                    useControlProxy: true # if the Loki API is not available from the switches directly, use the Control Node as a proxy
-            unixExporterCollectors: # list of node-exporter collectors to enable, https://grafana.com/docs/alloy/latest/reference/components/prometheus.exporter.unix/#collectors-list
-                - cpu
-                - filesystem
-                - loadavg
-                - meminfo
-            unixExporterEnabled: true
-            unixScrapeIntervalSeconds: 120
-            collectSyslogEnabled: true # collect /var/log/syslog on switches and forward to the lokiTargets
+        controlProxyURL: http://172.30.1.1:31028
+        lokiTargets:
+          grafana_cloud: # target name, multiple targets can be configured
+              basicAuth: # optional
+                  password: "<password>"
+                  username: "<username>"
+              labels: # labels to be added to all logs
+                  env: env-1
+              url: https://logs-prod-021.grafana.net/loki/api/v1/push
+              useControlProxy: true # if the Loki API is not available from the switches directly, use the Control Node as a proxy
+        prometheusTargets:
+          grafana_cloud: # target name, multiple targets can be configured
+              basicAuth: # optional
+                  password: "<password>"
+                  username: "<username>"
+              labels: # labels to be added to all metrics
+                  env: env-1
+              sendIntervalSeconds: 120
+              url: https://prometheus-prod-36-prod-us-west-0.grafana.net/api/prom/push
+              useControlProxy: true # if the Loki API is not available from the switches directly, use the Control Node as a proxy
+              unixExporterCollectors: # list of node-exporter collectors to enable, https://grafana.com/docs/alloy/latest/reference/components/prometheus.exporter.unix/#collectors-list
+                  - cpu
+                  - filesystem
+                  - loadavg
+                  - meminfo
+              collectSyslogEnabled: true # collect /var/log/syslog on switches and forward to the lokiTargets
 ```
 
 For additional options, see the `AlloyConfig` [struct in Fabric repo](https://github.com/githedgehog/fabric/blob/master/api/meta/alloy.go).
diff --git a/docs/install-upgrade/overview.md b/docs/install-upgrade/overview.md
@@ -15,7 +15,7 @@
 ## Overview of Install Process
 
 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).
+preparation and configuration. To install the vlab see [Vlab Overview](../vlab/overview.md).
 
 Download and install `hhfab` following instructions from the [Download](../getting-started/download.md) section.
 
@@ -34,13 +34,17 @@ The main steps to install Fabric are:
 1. Prepare supported switches
     1. Boot them into ONIE Install Mode to have them automatically provisioned
 
-## Build Control Node configuration and installer
+## Build Control Node configuration and Installer
+Hedgehog has created a command line utility, called `hhfab`, that will help generate the wiring diagram, validate the supplied configurations, and generate an installation image (.img) suitable for writing to a disk. 
 
-### HHFAB commands
-- `hhfab init --wiring wiring-lab.yaml`
-- edit the `fab.yaml` file for your needs
-- `hhfab validate`
-- `hhfab build`
+### HHFAB commands to make a bootable image
+1. `hhfab init --wiring wiring-lab.yaml`
+1. edit the `fab.yaml` file for your needs
+    1. ensure the correct boot disk (eg `/dev/sda`) and control node NIC names are supplied
+1. `hhfab validate`
+1. `hhfab build --usb`
+
+The installer for the fabric will be generated in `$WORKDIR/result`. This installation image is 7.5 GB in size.
 
 ### Burn USB image to disk
 !!! warning ""
@@ -49,18 +53,19 @@ The main steps to install Fabric are:
 - 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/).
 
-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
 
 This control node should be given a static IP address. Either a lease or statically assigned. 
 
-1. Configure the server to use UEFI boot without secure boot
+1. Configure the server to use UEFI boot **without** secure boot
+
+1. Attach the image to the server either by inserting via USB, or attaching via virtual media. 
 
-1. Attach the image to the server either by inserting via USB, or attaching via virtual media. After this step the process is automated
+1. Select boot off of the attached media, after this step the process is **automated**. The remaining steps are for your knowledge
 
 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
@@ -78,9 +83,11 @@ This control node should be given a static IP address. Either a lease or statica
 
 ### Fabric Manages Switches
 
-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.
+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.
 
 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 
+- use the arrow keys to select the boot pod TODO (use the specific name)
+- the logs of the pod will be displayed showing the dhcp lease process
+- use the switches screen of `k9s` to see the heartbeat column to verify the connection between switch and controller.
+    - to see the switches type `:switches` (like a vim command) into `k9s`