From 0d5e32d847dbccf08ddbbaae7ff84bf6b9b1416d Mon Sep 17 00:00:00 2001 From: Fredi Raspall Date: Mon, 30 Sep 2024 09:51:56 +0200 Subject: [PATCH] Misc. minor corrections. Including: * Unified some formatting. * removed spurious ```yaml that was being rendered. * Fixed the definitions for VLANNamespace and IPv4Namespace, which were swapped. --- docs/concepts/overview.md | 10 +++++----- docs/user-guide/connections.md | 16 ++++++++-------- docs/user-guide/devices.md | 14 +++++++------- docs/user-guide/vpcs.md | 31 ++++++++++++++++--------------- 4 files changed, 36 insertions(+), 35 deletions(-) diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md index d512bb1..fea15a0 100644 --- a/docs/concepts/overview.md +++ b/docs/concepts/overview.md @@ -29,9 +29,9 @@ systems. Wiring Diagram consists of the following resources: -* "Devices": describes any device in the Fabric +* __Devices__: describes *any* device in the Fabric * __Switch__: configuration of the switch, containing for example: port group speeds, port breakouts, switch IP/ASN - * __Server__: any physical server attached to the Fabric including Control Nodes + * __Server__: *any* physical server attached to the Fabric including Control Nodes * __Connection__: *any* logical connection for devices * usually it's a connection between two or more ports on two different devices * for example: MCLAG Peer Link, Unbundled/MCLAG server connections, Fabric connection between spine and leaf @@ -41,8 +41,8 @@ Wiring Diagram consists of the following resources: ### User-facing API * VPC API - * __VPC__: Virtual Private Cloud, similar to the public cloud VPC it provides an isolated private network for the - resources, with support for multiple subnets, each with user-provided VLANs and on-demand DHCP + * __VPC__: Virtual Private Cloud, similar to a the public cloud VPC, provides an isolated private network for the + resources, with support for multiple subnets, each with user-defined VLANs and optional DHCP service * __VPCAttachment__: represents a specific VPC subnet assignment to the Connection object which means exact server port to a VPC binding * __VPCPeering__: enables VPC-to-VPC connectivity (could be Local where VPCs are used or Remote peering on the border/mixed leaves) * External API @@ -96,5 +96,5 @@ Control plane and switch agent. * Additionally, it's running the admission webhook for Hedgehog's CRD APIs * The Agent is watching for the corresponding Agent CRD in Kubernetes API * It applies the changes and saves the new configuration locally - * It reports some status and information back to the API + * It reports status and information back to the API * It can perform reinstallation and reboot of SONiC diff --git a/docs/user-guide/connections.md b/docs/user-guide/connections.md index 64a9cfa..c7c431a 100644 --- a/docs/user-guide/connections.md +++ b/docs/user-guide/connections.md @@ -1,18 +1,18 @@ # Connections -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. +`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. -All connections referencing some switch and device ports. Only port naming defined by switch profiles can be used in -the wiring diagram for the switches, NOS (or any other) port names aren't supported. Server ports aren't validated by +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 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. +There are several types of connections. ## Server connections (user-facing) -Server connections are used to connect workload servers to the switches. +Server connections are used to connect workload servers to switches. ### Unbundled @@ -114,7 +114,7 @@ the Fabric features. ### Fabric -A Fabric Connections is used between specific spine and leaf, it covers all actual wires between a single pair. +A Fabric Connection is used between a specific pair of spine and leaf switches, representing all of the wires between them. ```yaml apiVersion: wiring.githedgehog.com/v1alpha2 @@ -225,7 +225,7 @@ Internet, to other networks, or to some other systems such as DHCP, NTP, LMA, or ### StaticExternal -StaticExternal connections provide a simple way to connect things like DHCP servers directly to the Fabric by connecting +`StaticExternal` connections provide a simple way to connect things like DHCP servers directly to the Fabric by connecting them to specific switch ports. ```yaml diff --git a/docs/user-guide/devices.md b/docs/user-guide/devices.md index bb4a233..7aad39e 100644 --- a/docs/user-guide/devices.md +++ b/docs/user-guide/devices.md @@ -1,15 +1,15 @@ # Switches and Servers -All devices in the Hedgehog Fabric are divided into two groups: switches and servers, represented by the corresponding -`Switch` and `Server` objects in the API. These objects are needed to define all participants of the Fabric and their -roles in the Wiring Diagram as well as [Connections](./connections.md) between them. +All devices in a Hedgehog Fabric are divided into two groups: switches and servers, represented by the corresponding +`Switch` and `Server` objects in the API. These objects are needed to define all of the participants of the Fabric and their +roles in the Wiring Diagram, together with `Connection` objects (see [Connections](./connections.md)). ## Switches 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. 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. +IP addresses, and more. Additionally, a `Switch` contains a reference to a `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 @@ -39,7 +39,7 @@ spec: vlanNamespaces: # Defines which VLANs could be used to attach servers - default vtepIP: 172.30.12.100/32 - groups: # Defines which groups the switch belongs to + groups: # Defines which groups the switch belongs to, by referring to SwitchGroup objects - some-group redundancy: # Optional field to define that switch belongs to the redundancy group group: eslag-1 # Name of the redundancy group @@ -63,7 +63,7 @@ Redundancy groups are used to define the redundancy between switches. It's a reg switches and currently it could be MCLAG or ESLAG (EVPN MH / ESI). A switch can only belong to a single redundancy group. -MCLAG is only supported for pair of switches and ESLAG is supported for up to 4 switches. Multiple types of redundancy +MCLAG is only supported for pairs of switches and ESLAG is supported for up to 4 switches. Multiple types of redundancy groups can be used in the fabric simultaneously. Connections with types `mclag` and `eslag` are used to define the servers connections to switches. They are only diff --git a/docs/user-guide/vpcs.md b/docs/user-guide/vpcs.md index f4c5452..72dbc42 100644 --- a/docs/user-guide/vpcs.md +++ b/docs/user-guide/vpcs.md @@ -2,8 +2,8 @@ ## VPC -A Virtual Private Cloud (VPC) is similar to a public cloud VPC. It provides an isolated private network for the -resources with support for multiple subnets, each with user-provided VLANs and on-demand DHCP. +A Virtual Private Cloud (VPC) is similar to a public cloud VPC. It provides an isolated private network with support for multiple subnets, +each with user-defined VLANs and optional DHCP services. ```yaml apiVersion: vpc.githedgehog.com/v1alpha2 @@ -12,8 +12,8 @@ metadata: name: vpc-1 namespace: default spec: - ipv4Namespace: default # Limits to which subnets could be used by VPC to guarantee non-overlapping IPv4 ranges - vlanNamespace: default # Limits to which switches VPC could be attached to guarantee non-overlapping VLANs + ipv4Namespace: default # Limits which subnets can the VPC use to guarantee non-overlapping IPv4 ranges + vlanNamespace: default # Limits which Vlan Ids can the VPC use to guarantee non-overlapping VLANs defaultIsolated: true # Sets default behavior for the current VPC subnets to be isolated defaultRestricted: true # Sets default behavior for the current VPC subnets to be restricted @@ -48,8 +48,8 @@ spec: subnet: 10.10.100.0/24 vlan: 1100 - permit: # Defines which subnets of the current VPC could communicate to each other, applied on top of subnets "isolated" flag (doesn't affect VPC peering) - - [subnet-1, subnet-2, subnet-3] # 1, 2 and 3 subnets could communicate to each other + permit: # Defines which subnets of the current VPC can communicate to each other, applied on top of subnets "isolated" flag (doesn't affect VPC peering) + - [subnet-1, subnet-2, subnet-3] # 1, 2 and 3 subnets can communicate to each other - [subnet-4, subnet-5] # Possible to define multiple lists staticRoutes: # Optional, static routes to be added to the VPC @@ -68,11 +68,12 @@ allowed by permit lists. _Restricted subnet_ means that all hosts in the subnet are isolated from each other within the subnet. -A Permit list is defined as a list of subnets that could communicate with each other. +A Permit list contains a list. Every element of the list is a set of subnets that can communicate with each other. -### Third-party DHCP server -In case you use a third-party DHCP server by configuring `spec.subnets..dhcp.relay`, additional information is +### Third-party DHCP server configuration + +In case you use a third-party DHCP server, by configuring `spec.subnets..dhcp.relay`, additional information is added to the DHCP packet forwarded to the DHCP server to make it possible to identify the VPC and subnet. This information is added under the RelayAgentInfo (option 82) in the DHCP packet. The relay sets two suboptions in the packet: @@ -98,7 +99,7 @@ metadata: spec: connection: server-1--mclag--s5248-01--s5248-02 # Connection name representing the server port(s) subnet: vpc-1/default # VPC subnet name - nativeVLAN: true # Optional, if true the port will be configured as a native VLAN port (untagged) + nativeVLAN: true # (Optional) if true, the port will be configured as a native VLAN port (untagged) ``` ## VPCPeering @@ -108,7 +109,7 @@ A VPCPeering enables VPC-to-VPC connectivity. There are two types of VPC peering * Local: peering is implemented on the same switches where VPCs are attached * Remote: peering is implemented on the border/mixed leaves defined by the `SwitchGroup` object -VPC peering is only possible between VPCs attached to the same IPv4 namespace. +VPC peering is only possible between VPCs attached to the same IPv4 namespace (see [IPv4Namespace](#ipv4namespace)) ### Local VPC peering @@ -144,7 +145,6 @@ spec: It's possible to specify which specific subnets of the peering VPCs could communicate to each other using the `permit` field. -```yaml ```yaml apiVersion: vpc.githedgehog.com/v1alpha2 kind: VPCPeering @@ -165,8 +165,8 @@ spec: ## IPv4Namespace -An IPv4Namespace defines non-overlapping VLAN ranges for attaching servers. Each switch belongs to a list of VLAN -namespaces with non-overlapping VLAN ranges. +An `IPv4Namespace` defines a set of (non-overlapping) IPv4 address ranges available for use by VPC subnets. +Each VPC belongs to a specific IPv4 namespace. Therefore, its subnet prefixes must be from that IPv4 namespace. ```yaml apiVersion: vpc.githedgehog.com/v1alpha2 @@ -181,7 +181,8 @@ spec: ## VLANNamespace -A VLANNamespace defines non-overlapping IPv4 ranges for VPC subnets. Each VPC belongs to a specific IPv4 namespace. +A `VLANNamespace` defines a set of VLAN ranges available for attaching servers to switches. Each switch can belong to one or more +disjoint VLANNamespaces. ```yaml apiVersion: wiring.githedgehog.com/v1alpha2