Skip to content

document virtual externals #105

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

document virtual externals #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
98f1968
external updates
edipascale Apr 11, 2025
29df76f
vlab: update resources and gen info
edipascale Apr 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 16 additions & 9 deletions docs/user-guide/external.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,12 +61,17 @@ apiVersion: vpc.githedgehog.com/v1beta1
kind: External
metadata:
name: default--5835
annotations:
type.hhfab.githedgehog.com: hw # Tells Fabric that this is a physical device
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there is no need to mention this annotation - it's only used for the hybrid vlab which isn't documented in public docs anyways

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, but this documentation is not only public facing, it's also the first reference for us internally. I expect a new hire to look at this for guidance, and without these annotations hhfab vlab up will fail on start in an hybrid vlab, so isn't it worth documenting?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if we're documenting hybrid vlab it should be clearly separate from any other docs as it's a unique case only for the hybrid vlab. maybe we can introduce a separate section about it

spec:
ipv4Namespace: # VPC IP Namespace
inboundCommunity: # BGP Standard Community of routes from Edge devices
outboundCommunity: # BGP Standard Community required to be assigned on prefixes advertised from Fabric
```

!!! note
In a [VLAB](../vlab/overview.md) environment only, if the `hw` type annotation is not included, Fabric will emulate this external with an FRR VM.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need for the note, same reason


### Connection

A `Connection` of type `external` is used to identify the switch port on Border leaf that is cabled with an Edge device.
Expand All @@ -76,13 +81,18 @@ apiVersion: wiring.githedgehog.com/v1beta1
kind: Connection
metadata:
name: # specified or generated
annotations:
type.hhfab.githedgehog.com: hw # Tells fabric that this is a physical link
spec:
external:
link:
switch:
port: ds3000/E1/1
```

!!! note
In a [VLAB](../vlab/overview.md) environment only, if the `hw` type annotation is not included, Fabric will add a virtual link to the virtual external VM.

### External Attachment

`External Attachment` defines BGP Peering and traffic connectivity between a Border leaf and `External`. Attachments are
Expand Down Expand Up @@ -174,18 +184,13 @@ on the port `E1/2`. Specifying `vpc-1` is required to receive any prefixes adver
- apiVersion: vpc.githedgehog.com/v1beta1
kind: External
metadata:
creationTimestamp: "2024-11-26T21:24:32Z"
generation: 1
labels:
fabric.githedgehog.com/ipv4ns: default
name: hedgeedge
namespace: default
resourceVersion: "57628"
uid: a0662988-73d0-45b3-afc0-0d009cd91ebd
annotations:
type.hhfab.githedgehog.com: hw
spec:
inboundCommunity: 65102:5000
ipv4Namespace: default
outboundCommunity: 5000:6510
inboundCommunity: 65102:5000
outboundCommunity: 5000:65102
```

#### Connection
Expand All @@ -200,6 +205,8 @@ apiVersion: wiring.githedgehog.com/v1beta1
kind: Connection
metadata:
name: switchBorder--external--HedgeEdge
annotations:
type.hhfab.githedgehog.com: hw
spec:
external:
link:
Expand Down
14 changes: 9 additions & 5 deletions docs/vlab/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,12 @@ and fairly up-to-date packages.
The following packages needs to be installed: `qemu-kvm socat`. Docker is also required, to login
into the OCI registry.

By default, the VLAB topology is Spine-Leaf with 2 spines, 2 MCLAG leaves and 1 non-MCLAG leaf. Optionally, you can
choose to run the default Collapsed Core topology using flag `--fabric-mode collapsed-core` (or `-m collapsed-core`)
which only consists of 2 switches.
By default, the VLAB topology is Spine-Leaf with 2 spines, 2 MCLAG leaves,
2 ESLAG leaves and 1 non-LAG leaf, plus a virtual external device. Optionally, you can
choose to run the default Collapsed Core topology using flag `--fabric-mode collapsed-core`
(or `-m collapsed-core`) which only consists of 2 switches and the virtual external.
You can also fine tune how many switches, servers and externals are generated via
command line parameters; see `hhfab vlab gen --help` for all the available options.

You can calculate the system requirements based on the allocated resources to the VMs using the following table:

Expand All @@ -36,11 +39,12 @@ You can calculate the system requirements based on the allocated resources to th
| Control Node | 6 | 6GB | 100GB |
| Test Server | 2 | 768MB | 10GB |
| Switch | 4 | 5GB | 50GB |
| Virtual External | 4 | 5GB | 50GB |

These numbers give approximately the following requirements for the default topologies:

* Spine-Leaf: 38 vCPUs, 36352 MB, 410 GB disk
* Collapsed Core: 22 vCPUs, 19456 MB, 240 GB disk
* Spine-Leaf: 50 vCPUs, 44544 MB, 500 GB disk
* Collapsed Core: 26 vCPUs, 24576 MB, 290 GB disk

Usually, none of the VMs will reach 100% utilization of the allocated resources, but as a rule of thumb you should make
sure that you have at least allocated RAM and disk space for all VMs.
Expand Down
54 changes: 28 additions & 26 deletions docs/vlab/running.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,18 +16,19 @@ ubuntu@docs:~$ hhfab init --dev
```
## VLAB Topology

By default, `hhfab init` creates 2 spines, 2 MCLAG leaves and 1 non-MCLAG leaf with 2 fabric connections (between each spine and leaf), 2 MCLAG peer links and 2 MCLAG session links as well as 2 loopbacks per leaf for implementing VPC loopback workaround. To generate the preceding topology, `hhfab vlab gen`. You can also configure the number of spines, leafs, connections, and so on. For example, flags `--spines-count` and `--mclag-leafs-count` allow you to set the number of spines and MCLAG leaves, respectively. For complete options, `hhfab vlab gen -h`.
By default, `hhfab init` creates 2 spines, 2 MCLAG leaves, 2 ESLAG leaves and 1 non-MCLAG leaf with 2 fabric connections (between each spine and leaf), 2 MCLAG peer links and 2 MCLAG session links as well as 2 loopbacks per leaf for implementing VPC loopback workaround. It will also generate a VM to emulate an [External](../user-guide/external.md) device and two connections to it from the ESLAG leaves. To generate the preceding topology, `hhfab vlab gen`. You can also configure the number of spines, leafs, connections, and so on. For example, flags `--spines-count` and `--mclag-leafs-count` allow you to set the number of spines and MCLAG leaves, respectively. For complete options, `hhfab vlab gen -h`.

```console
ubuntu@docs:~$ hhfab vlab gen
21:27:16 INF Hedgehog Fabricator version=v0.36.1
21:27:16 INF Building VLAB wiring diagram fabricMode=spine-leaf
21:27:16 INF >>> spinesCount=2 fabricLinksCount=2
21:27:16 INF >>> eslagLeafGroups=2
21:27:16 INF >>> mclagLeafsCount=2 mclagSessionLinks=2 mclagPeerLinks=2
21:27:16 INF >>> orphanLeafsCount=1 vpcLoopbacks=2
21:27:16 INF >>> mclagServers=2 eslagServers=2 unbundledServers=1 bundledServers=1
21:27:16 INF Generated wiring file name=vlab.generated.yaml
10:38:06 INF Hedgehog Fabricator version=v0.36.1
10:38:06 INF Building VLAB wiring diagram fabricMode=spine-leaf
10:38:06 INF >>> spinesCount=2 fabricLinksCount=2
10:38:06 INF >>> eslagLeafGroups=2
10:38:06 INF >>> mclagLeafsCount=2 mclagSessionLinks=2 mclagPeerLinks=2
10:38:06 INF >>> orphanLeafsCount=1 vpcLoopbacks=2
10:38:06 INF >>> mclagServers=2 eslagServers=2 unbundledServers=1 bundledServers=1
10:38:06 INF >>> externalCount=1 externalMclagConnCount=0 externalEslagConnCount=2 externalOrphanConnCount=0
10:38:06 INF Generated wiring file name=vlab.generated.yaml
```
You can jump [to the instructions](#build-the-installer-and-start-vlab) to start VLAB, or see the next section for customizing the topology.

Expand All @@ -36,28 +37,29 @@ If a Collapsed Core topology is desired, after the `hhfab init --dev` step, edit

```console
ubuntu@docs:~$ hhfab vlab gen
11:39:02 INF Hedgehog Fabricator version=v0.36.1
11:39:02 INF Building VLAB wiring diagram fabricMode=collapsed-core
11:39:02 INF >>> mclagLeafsCount=2 mclagSessionLinks=2 mclagPeerLinks=2
11:39:02 INF >>> orphanLeafsCount=0 vpcLoopbacks=2
11:39:02 INF >>> mclagServers=2 eslagServers=2 unbundledServers=1 bundledServers=1
11:39:02 INF Generated wiring file name=vlab.generated.yaml

11:21:02 INF Hedgehog Fabricator version=v0.36.1
11:21:02 INF Building VLAB wiring diagram fabricMode=collapsed-core
11:21:02 INF >>> mclagLeafsCount=2 mclagSessionLinks=2 mclagPeerLinks=2
11:21:02 INF >>> orphanLeafsCount=0 vpcLoopbacks=2
11:21:02 INF >>> mclagServers=2 eslagServers=0 unbundledServers=1 bundledServers=1
11:21:02 INF >>> externalCount=1 externalMclagConnCount=2 externalEslagConnCount=0 externalOrphanConnCount=0
11:21:02 INF Generated wiring file name=vlab.generated.yaml
```

### Custom Spine Leaf
Or you can run custom topology with 2 spines, 4 MCLAG leaves and 2 non-MCLAG leaves using flags:
Or you can run custom topology with 2 spines, 4 MCLAG leaves, 2 non-LAG leaves and no externals using flags:

```console
ubuntu@docs:~$ hhfab vlab gen --mclag-leafs-count 4 --orphan-leafs-count 2
11:41:06 INF Hedgehog Fabricator version=v0.36.1
11:41:06 INF Building VLAB wiring diagram fabricMode=spine-leaf
11:41:06 INF >>> spinesCount=2 fabricLinksCount=2
11:41:06 INF >>> eslagLeafGroups=""
11:41:06 INF >>> mclagLeafsCount=4 mclagSessionLinks=2 mclagPeerLinks=2
11:41:06 INF >>> orphanLeafsCount=2 vpcLoopbacks=2
11:41:06 INF >>> mclagServers=2 eslagServers=2 unbundledServers=1 bundledServers=1
11:41:06 INF Generated wiring file name=vlab.generated.yaml
ubuntu@docs:~$ hhfab vlab gen --mclag-leafs-count 4 --orphan-leafs-count 2 --externals 0
12:03:39 INF Hedgehog Fabricator version=v0.36.1
12:03:39 INF Building VLAB wiring diagram fabricMode=spine-leaf
12:03:39 INF >>> spinesCount=2 fabricLinksCount=2
12:03:39 INF >>> eslagLeafGroups=""
12:03:39 INF >>> mclagLeafsCount=4 mclagSessionLinks=2 mclagPeerLinks=2
12:03:39 INF >>> orphanLeafsCount=2 vpcLoopbacks=2
12:03:39 INF >>> mclagServers=2 eslagServers=0 unbundledServers=1 bundledServers=1
12:03:39 INF >>> externalCount=0 externalMclagConnCount=0 externalEslagConnCount=0 externalOrphanConnCount=0
12:03:39 INF Generated wiring file name=vlab.generated.yaml
```

Additionally, you can pass extra Fabric configuration items using flags on `init` command or by passing a configuration
Expand Down