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
@@ -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 shutdown but before the boot up 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:
+```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,32 @@ 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).
+
+```{.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
+```
+
+### Gateway to External Connections
+
+TODO: give the YAML examples

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.

docs/user-guide/gateway.md

@@ -0,0 +1,121 @@
+# Gateway
+
+## Gateway Connections
+
+The Gateway provides network services like: peering, NAT, and firewall for
+traffic entering and exiting the fabric, as well as traffic between VPCs. The
+Gateway is connected to the fabric spines, a minimum of two connections is
+required. The Gateway has its own ASN to use in the BGP routing protocol.
+Connections between the fabric and the outside world should use the Gateway.
+For example a data center WAN connection should meet the fabric at the Gateway.
+
+
+## Gateway Peering
+
+[VPC Peerings](vpcs.md#vpcpeering) provide VPC to VPC connectivity by way of the switches in the fabric.
+These peerings use route leaking inside the switch fabric to allow on VPC to communicate with another VPC.
+While this works well for many types of connections, especially those that need the full cut-through bandwidth of the fabric, the switch fabric is limited in the functionality in can provide with regard to the peering.
+For example, any peering that requires network address translation (NAT), or firewalling, and other functionality beyond the capabilities of the switch fabric cannot use a standard VPC peering.
+
+For such cases, Hedgehog provides a Gateway Peering feature in fabrics that have attached gateways.
+A Gateway Peering provides connectivity between VPCs (or externals) but causes the traffic to flow through a gateway node which can provide advanced services such as NAT and firewall.
+The downside is that the peering is limited in bandwidth to the capacity of the gateway node(s) instead of the full cut-through bandwidth of the fabric.
+
+
+### Simple Gateway Peering Between VPCs
+
+
+```{.yaml .annotate linenums="1" title="gw-peer.yaml"}
+apiVersion: gateway.githedgehog.com/v1alpha1
+kind: Peering
+metadata:
+  name: vpc-1--vpc-2
+  namespace: default
+spec:
+  peering:
+    vpc-1:
+      expose:
+        - ips:
+          - cidr: 10.0.0.0/24 # Expose all IP address in the 10.0.0.0/24 CIDR block to vpc-2
+    vpc-2:
+      expose:
+        - ips:
+          - cidr: 192.168.0.0/16 # Expose all IP addresses in the 192.168.0.0/16 CIDR block to vpc-1
+```
+
+A simple peering with no services deployed between the VPCs. This traffic will
+transit the gateway node.
+
+### Gateway Peering with stateless NAT
+
+```{.yaml .annotate linenums="1" title="sl-gw-peer.yaml"}
+apiVersion: gateway.githedgehog.com/v1alpha1
+kind: Peering
+metadata:
+  name: vpc-1--sl-nat--vpc-2
+  namespace: default
+spec:
+  peering:
+    vpc-1:
+      expose:
+        - ips:
+          - cidr: 10.0.1.0/24 # Expose all IP address in the 10.0.1.0/24 CIDR block to vpc-2
+          as:
+          - cidr: 10.11.11.0/24 # Cr
+    vpc-2:
+      expose:
+        - ips:
+          - cidr: 10.0.2.0/24
+          as:
+          - cidr: 10.22.22.0/24
+
+```
+
+Stateless NAT blindly translates source and destination IP addresses for all packets that traverse
+the peering, but it does not maintain any connection or flow state for the
+connection. The mapping is one for one, to reach `10.0.1.3` on vpc-1 from
+vpc-2, use `10.11.11.3` as the destination address. The cidr for IP addresses
+must be equal.
+
+
+### Gateway Peering with stateful NAT
+
+```{.yaml .annotate linenums="1" title="gw-sf-nat-peer.yaml"}
+apiVersion: gateway.githedgehog.com/v1alpha1
+kind: Peering
+metadata:
+  name: vpc-1--sf-nat--vpc-2
+  namespace: default
+spec:
+  peering:
+    vpc-01:
+      expose:
+        # Allow 10.0.0.0/24 addresses to talk to vpc-2
+        # Because of stateful NAT, traffic from vpc-2 to vpc-1 is only allowed if there is
+        # a flow table entry created by a traffic initiated from vpc-1 to vpc-2.
+        - ips:
+          - cidr: 10.0.0.0/24
+          as:
+          - cidr: 10.0.1.0/32  # but, NAT those addresses using the addresses in 10.0.1.0/31
+          nat:  # Contains the nat configuration
+            stateful:  # Make NAT stateful, connections initiated from vpc-1 to vpc-2 will be added to the flow table
+              idleTimeout: 5m # Timeout connections after 5 minutes of inactivity (no packets received)
+    vpc-2:
+      expose:
+        # Allows traffic from vpc-1 to vpc-2 on these addresses.
+        # Connections must be initiated from vpc-1 to vpc-2 due to flow tracking.
+        - ips:
+          - cidr: 192.168.0.0/16
+        # Currently, only one VPC of an expose block can use NAT when using stateful NAT.
+        # This restriction will be lifted in a future release.
+```
+
+Stateful NAT uses a flow table to track established connections.
+When traffic is initiated from vpc-1 to vpc-2, the flow table is updated with the connection details.
+In the return direction (from `vpc-2` to `vpc-1` in the example below), the flow table is consulted to determine if the packet is part of an established connection.
+If it is, the packet is allowed to pass through the peering.  If it is not, the packet is dropped.
+This behavior allows use of stateful NAT as a simple firewall.
+
+### Gateway Peering with NAT for External Connections
+
+TODO: Please write this section once external gateway peering support is complete.

docs/user-guide/overview.md

@@ -6,6 +6,7 @@ This chapter gives an overview of the main features of Hedgehog Fabric and their
 - [**Connections**](connections.md): Describes the different types of network links, such as workload server connections, switch interconnects, and external peering links.
 - [**VPCs and Namespaces**](vpcs.md): Explains virtual private cloud configurations, subnet management, and peering mechanisms.
 - [**External Peering**](external.md): Details how to connect the fabric to external networks and services through border leaf peering.
+- [**Gateway**](grafana.md): Explains gateway configuration and gateway based Peerings for NAT and firewall functionality.
 - [**Fabric Shrink/Expand**](shrink-expand.md): Guides users on adding, removing, or replacing switches within the fabric.
 - [**Switch Profiles and Port Naming**](profiles.md): Defines switch profiles, port naming conventions, and supported configurations.
 - [**Grafana Dashboards**](grafana.md): Provides insights into monitoring and visualization tools for tracking fabric performance and health.