Basic Gateway Documentation

docs/install-upgrade/build-wiring.md

@@ -367,6 +367,20 @@ spec:
   redundancy: {}
   role: spine
 #
+# GatewayList
+#
+---
+apiVersion: gateway.githedgehog.com/v1alpha1
+kind: Gateway
+metadata:
+  name: gateway-1
+  namespace: fab
+spec:
+  interfaces:
+    enp2s1: {}
+    enp2s2: {}
+  logs: {}
+#
 # ConnectionList
 #
 ---
@@ -497,4 +511,28 @@ spec:
         port: leaf-04/E1/8
       spine:
         port: spine-02/E1/2/4
+---
+apiVersion: wiring.githedgehog.com/v1beta1
+kind: Connection
+metadata:
+  name: spine-01--gateway--gateway-1
+spec:
+  gateway:
+    links:
+    - gateway:
+        port: gateway-1/enp2s1
+      switch:
+        port: spine-01/E1/3/1
+---
+apiVersion: wiring.githedgehog.com/v1beta1
+kind: Connection
+metadata:
+  name: spine-02--gateway--gateway-1
+spec:
+  gateway:
+    links:
+    - gateway:
+        port: gateway-1/enp2s2
+      switch:
+        port: spine-02/E1/3/1
 ```

docs/install-upgrade/config.md

@@ -104,6 +104,19 @@ spec:
     interface: eno1
 
 # Currently only one ControlNode is supported
+---
+apiVersion: fabricator.githedgehog.com/v1beta1
+kind: FabNode
+metadata:
+  name: gateway-1
+  namespace: fab
+spec:
+  roles:
+    - gateway
+  bootstrap:
+   disk: "/dev/sda" # disk to install OS on, e.g. "sda" or "nvme0n1"
+  management: # interface that connects gateway to private hh managment network
+    interface: enp2s0
 ```
 
 ### Configure Control Node and Switch Users

docs/install-upgrade/install.md

@@ -27,8 +27,11 @@ The main steps to install Fabric are:
     1. [Select Fabric Configuration](./config.md)
     1. [Build Control Node configuration and installer](#build-control-node-configuration-and-installer)
 1. [Install Control Node](#install-control-node)
-    1. Insert USB with control-os image into Fabric Control Node
+    1. Attach the ISO with control-os image to the Fabric Control Node
     1. Boot the node off the USB to initiate the installation
+1. [Install Gateway Node](#install-gateway-node)
+    1. Attach the ISO with gateway-os image to the gateway node
+    1. Boot the node off the media to initiate the installation
 1. Prepare Management Network
     1. Connect management switch to Fabric control node
     1. Connect 1GbE Management port of switches to management switch
@@ -94,7 +97,7 @@ This control node should be given a static IP address. Either a lease or statica
 
 1. Once the installation is complete, the system automatically reboots.
 
-1. After the system has shutdown but before the boot up process reaches the operating system, **remove the USB image from the system**. Removal during the UEFI boot screen is acceptable.
+1. After the system has shut down but before the boot process reaches the operating system, **remove the USB image from the system**. Removal during the UEFI boot screen is acceptable.
 
 1. Upon booting into the freshly installed system, the fabric installation will **automatically begin**
     1. If the insecure `--dev` flag was passed to `hhfab init` the password for the `core` user is `HHFab.Admin!`, the switches have two users created `admin` and `op`. `admin` has administrator privileges and password `HHFab.Admin!`, whereas the `op` user is a read-only, non-sudo user with password `HHFab.Op!`.
@@ -126,3 +129,38 @@ At this stage, the fabric hands out DHCP addresses to the switches via the manag
 - 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`
+
+## Install Gateway Node
+
+All of the management of the gateway node is provided through the control node. The management
+network of the gateway node should reside on the same management network as the
+switches and control node. As with the control node, use the virtual media
+feature of the BMC to attach the bootable ISO to the node. Alternatively a USB
+image is also available, if it can be physically attached to the server.
+
+1. Complete the [installation of the control node](#install-control-node)
+
+1. Attach the image to the server either by inserting via USB, or attaching via virtual media
+
+1. Configure the server to use UEFI boot **without** secure boot
+
+1. Select boot off of the attached media, the installation process is automated
+
+1. Once the gateway node has booted, it logs in automatically and begins the installation process
+    1. Optionally use `journalctl -f -u flatcar-install.service` to monitor progress
+
+1. Once the installation is complete, the system automatically reboots
+
+1. After the system has shut down but before the boot process reaches the operating system, **remove the virtual media from the system**. Removal during the UEFI boot screen is acceptable
+
+1. Upon booting into the freshly installed system, the gateway installation
+   will automatically begin. The gateway node acts as a K3S agent
+
+1. Confirm that the control node and gateway node are communicating, from the
+   control node, see that the gateway `STATUS` is `Ready`:
+```console
+core@control-1 ~ $ kubectl get nodes
+NAME        STATUS   ROLES                AGE    VERSION
+control-1   Ready    control-plane,etcd   2d2h   v1.34.1+k3s1
+gateway-1   Ready    <none>               2d2h   v1.34.1+k3s1
+```

docs/user-guide/connections.md

@@ -1,12 +1,13 @@
 # Connections
 
 `Connection` objects represent logical and physical connections between the devices in the Fabric (`Switch`,
-`Server` and `External` objects) and are needed to define all the connections in the Wiring Diagram.
+`Server`, `Gateway`,  and `External` objects) and are needed to define all the connections in the Wiring Diagram.
 
 All connections reference switch or server ports. Only port names defined by switch profiles can be used in
-the wiring diagram for the switches. NOS (or any other) port names aren't supported. Currently, server ports aren't validated by
+the wiring diagram for the switches. In a Gateway connection the interface name
+on the gateway needs to be accurate. NOS (or any other) port names aren't supported. Currently, server ports aren't validated by
 the Fabric API other than for uniqueness. See the [Switch Profiles and Port Naming](../user-guide/profiles.md) section
-for more details.
+for more details on the switch port names.
 
 There are several types of connections.
 
@@ -291,3 +292,30 @@ spec:
       switch:
         port: s5248-03/E1/3
 ```
+
+## Gateway Connections
+
+### Spine to Gateway Connections
+
+These connection types are for gateway to spine connections. These connections
+will carry the traffic between VPCs that need network services, like NAT. More
+details about the Gateway are in the [Gateway section](gateway.md). In a mesh
+topology the connections will be between gateway and the leaf nodes. Note that
+gateway is not supported with mesh connections on TH5 leafs.
+
+```{.yaml .annotate linenums="1" filename="gw-connection.yaml"}
+apiVersion: wiring.githedgehog.com/v1beta1
+kind: Connection
+metadata:
+  name: spine-01--gateway--gateway-1
+  namespace: default
+spec:
+  gateway:
+    links:
+    - gateway:
+        ip: 172.30.128.9/31
+        port: gateway-1/enp2s1
+      switch:
+        ip: 172.30.128.8/31
+        port: spine-01/E1/5
+```

docs/user-guide/external.md

@@ -299,3 +299,5 @@ route-map HedgeOut permit 10
 
 bgp community-list standard HedgeIn permit 5000:65102
 ```
+
+See [Gateway Peering with NAT for External Connections](gateway.md#gateway-peering-with-nat-for-external-connections) for an examples on how to connect to external networks using NAT.