From 4c1f05c4c25edff55024b4cfc4ae20a84d4c69e9 Mon Sep 17 00:00:00 2001 From: Sergei Lukianov Date: Wed, 5 Jun 2024 09:47:06 -0700 Subject: [PATCH] Add SwitchProfile docs --- docs/install-upgrade/build-wiring.md | 4 ++ docs/install-upgrade/supported-devices.md | 2 + docs/reference/profiles.md | 3 + docs/user-guide/connections.md | 5 ++ docs/user-guide/devices.md | 12 ++-- docs/user-guide/profiles.md | 86 +++++++++++++++++++++++ 6 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 docs/reference/profiles.md create mode 100644 docs/user-guide/profiles.md diff --git a/docs/install-upgrade/build-wiring.md b/docs/install-upgrade/build-wiring.md index 316a524..47743c4 100644 --- a/docs/install-upgrade/build-wiring.md +++ b/docs/install-upgrade/build-wiring.md @@ -3,6 +3,10 @@ !!! 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. + In the meantime, to have a look at working wiring diagram for Hedgehog Fabric, run the sample generator that produces VLAB-compatible wiring diagrams: diff --git a/docs/install-upgrade/supported-devices.md b/docs/install-upgrade/supported-devices.md index ce58393..224319c 100644 --- a/docs/install-upgrade/supported-devices.md +++ b/docs/install-upgrade/supported-devices.md @@ -1,5 +1,7 @@ # Supported Devices +You can find mode details in the User Guide including [switch features and port naming](../user-guide/profiles.md). + ## Spine * DELL: S5232F-ON diff --git a/docs/reference/profiles.md b/docs/reference/profiles.md new file mode 100644 index 0000000..b74a47d --- /dev/null +++ b/docs/reference/profiles.md @@ -0,0 +1,3 @@ +# Switch Profiles + +TBD \ No newline at end of file diff --git a/docs/user-guide/connections.md b/docs/user-guide/connections.md index 7b0ea82..668e915 100644 --- a/docs/user-guide/connections.md +++ b/docs/user-guide/connections.md @@ -3,6 +3,11 @@ The `Connection` object represents logical and physical connections between any devices in the Fabric (`Switch`, `Server` and `External` objects). It's needed to define all connections between the devices in the Wiring Diagram. +All connections referencing some switch and device ports. Only port naming defined by switch profiles could be used in +the wiring diagram for thr switches, NOS (or any other) port names aren't supported. 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. + There are multiple types of connections. ## Server connections (user-facing) diff --git a/docs/user-guide/devices.md b/docs/user-guide/devices.md index ab18995..bb4a233 100644 --- a/docs/user-guide/devices.md +++ b/docs/user-guide/devices.md @@ -8,7 +8,8 @@ roles in the Wiring Diagram as well as [Connections](./connections.md) between t Switches are the main building blocks of the Fabric. They are represented by `Switch` objects in the API. These objects consist of basic metadata like name, description, location, role, as well as port group speeds, port breakouts, ASN, -IP addresses, and more. +IP addresses, and more. Additionally, it contains a reference to the `SwitchProfile` object that defines the switch +model and capabilities, more details can be found in the [Switch Profiles and Port Naming](./profiles.md) section. ```yaml apiVersion: wiring.githedgehog.com/v1alpha2 @@ -17,6 +18,7 @@ metadata: name: s5248-01 namespace: default spec: + profile: dell-s5248f-on # Mandatory reference to the SwitchProfile object defining the switch model and capabilities asn: 65101 # ASN of the switch description: leaf-1 ip: 172.30.10.100/32 # Switch IP that will be accessible from the Control Node @@ -25,11 +27,13 @@ spec: locationSig: sig: uuidSig: - portBreakouts: # Configures port breakouts for the switch - 1/55: 4x25G - portGroupSpeeds: # Configures port group speeds for the switch + portBreakouts: # Configures port breakouts for the switch, see the SwitchProfile for available options + E1/55: 4x25G + portGroupSpeeds: # Configures port group speeds for the switch, see the SwitchProfile for available options "1": 10G "2": 10G + portSpeeds: # Configures port speeds for the switch, see the SwitchProfile for available options + E1/1: 25G protocolIP: 172.30.11.100/32 # Used as BGP router ID role: server-leaf # Role of the switch, one of server-leaf, border-leaf and mixed-leaf vlanNamespaces: # Defines which VLANs could be used to attach servers diff --git a/docs/user-guide/profiles.md b/docs/user-guide/profiles.md new file mode 100644 index 0000000..3cc4f2c --- /dev/null +++ b/docs/user-guide/profiles.md @@ -0,0 +1,86 @@ +# Switch Profiles and Port Naming + +## Switch Profiles + +All supported switches have a `SwitchProfile` that defines the switch model, supported features, and available ports +with supported configurations such as port group and speeds as well as port breakouts. `SwitchProfiles` available +in-cluster or generated documentation can be found in the [Reference section](../reference/profiles.md). + +Each switch used in the wiring diagram should have a `SwitchProfile` references in the `spec.profile` of the `Switch` +object. + +Switch profile defines what features and ports are available on the switch. Based on the ports data in the profile, it's +possible to set port speeds (for non-breakout and non-group ports), port group speeds and port breakout modes in the +`Switch` object in the Fabric API. + +## Port Naming + +Each switch port is named using one of the the following formats: + +- `M` + - `` is the management port number starting from `1` (usually only one named `1` for most + switches) + +- `E/[/][.` is the ASIC or chassis number (usually only one named `1` for the most switches) + - `` is the port number on the ASIC or chassis, starting from `1` + - optional `/` is the breakout number for the port, starting from `1`, only for breakout ports and always + consecutive numbers independent of the lanes allocation and other implementation details + - optional `.` is the subinterface number for the port + +Examples of port names: + +- `M1` - management port +- `E1/1` - port `1` on the ASIC or chassis `1`, usually a first port on the switch +- `E1/55/1` - first breakout port of the switch port `55` on the ASIC or chassis `1` + +## Available Ports + +Each switch profile defines a set of ports available on the switch. Ports could be divided into the following types. + +### Directly configurable ports + +Non-breakout and non-group ports. Would have a reference to the port profile with default and available speeds. Could +be configured by setting the speed in the `Switch` object in the Fabric API: + +```yaml +.spec: + portSpeeds: + E1/1: 25G +``` + +### Port groups + +Ports that belong to a port group, non-breakout and not directly configurable. Would have a reference to the port group +which will have a reference to the port profile with default and available speeds. Port couldn't be configured directly, +speed configuration is applied to the whole group in the `Switch` object in the Fabric API: + +```yaml +.spec: + portGroupSpeeds: + "1": 10G +``` + +It'll set the speed of all ports in the group `1` to `10G`, e.g. if the group `1` contains ports `E1/1`, `E1/2`, `E1/3` +and `E1/4`, all of them will be set to `10G` speed. + +### Breakout ports + +Ports that are breakouts and non-group ports. Would have a reference to the port profile with default and available +breakout modes. Could be configured by setting the breakout mode in the `Switch` object in the Fabric API: + +```yaml +.spec: + portBreakouts: + E1/55: 4x25G +``` + +Configuring a port breakout mode will make "breakout" ports available for use in the wiring diagram. The breakout ports +are named as `E//`, e.g. `E1/55/1`, `E1/55/2`, `E1/55/3`, `E1/55/4` for +the example above. Omitting the breakout number is allowed for the first breakout port, e.g. `E1/55` is the same as +`E1/55/1`. The breakout ports are always consecutive numbers independent of the lanes allocation and other +implementation details. + +### Management ports + +Not configurable, no port profile, only used for connecting the switch to the control node.