From 143e173ec14f033b3d7f911f6c3e56d844bbac5e 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/architecture/fabric.md | 4 ++-- docs/concepts/overview.md | 10 +++++----- docs/contribute/docs.md | 2 +- docs/user-guide/connections.md | 18 +++++++++--------- docs/user-guide/devices.md | 14 +++++++------- docs/user-guide/vpcs.md | 33 +++++++++++++++++---------------- 6 files changed, 41 insertions(+), 40 deletions(-) diff --git a/docs/architecture/fabric.md b/docs/architecture/fabric.md index 0c27c7a..80c3691 100644 --- a/docs/architecture/fabric.md +++ b/docs/architecture/fabric.md @@ -60,7 +60,7 @@ describe how VPCs are actually implemented in the network to ensure a private vi attached subnets and import routes from its peered VPCs. The BGP instance in the tenant VRFs does not establish neighbor relationships and is purely used to advertise locally attached routes into the VPC (all VRFs with the same L3VNI) across leaves in the network. -* A VPC can have multuple subnets. Each subnet in the VPC is modeled as a VLAN on the switch. The VLAN is only locally +* A VPC can have multiple subnets. Each subnet in the VPC is modeled as a VLAN on the switch. The VLAN is only locally significant and a given subnet might have different VLANs on different leaves on the network. A globally significant VNI is assigned to each subnet. This VNI is used to extend the subnet across different leaves in the network and provides a view of single stretched L2 domain if the applications need it. @@ -77,7 +77,7 @@ describe how VPCs are actually implemented in the network to ensure a private vi To enable communication between 2 different VPCs, one needs to configure a VPC peering policy. The Hedgehog Fabric supports two different peering modes. -* Local Peering: A local peering directly imports routers from the other VPC locally. This is achieved by a simple +* Local Peering: A local peering directly imports routes from another VPC locally. This is achieved by a simple import route from the peer VPC. In case there are no locally attached workloads to the peer VPC the fabric automatically creates a stub VPC for peering and imports routes from it. This allows VPCs to peer with each other without the need for a dedicated peering leaf. If a local peering is done for a pair of VPCs which have locally diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md index d512bb1..8da8b26 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": describe *any* device in the Fabric and can be of two types: * __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 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/contribute/docs.md b/docs/contribute/docs.md index 6c0d8f9..8d79676 100644 --- a/docs/contribute/docs.md +++ b/docs/contribute/docs.md @@ -63,7 +63,7 @@ Where you can add pages by file name like `index.md` and page title will be take More details in the [MkDocs Pages plugin](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin). -### Abbreaviations +### Abbreviations You can find abbreviations in `includes/abbreviations.md` file. You can add various abbreviations there and all usages of the defined words in the documentation will get a highlight. diff --git a/docs/user-guide/connections.md b/docs/user-guide/connections.md index 64a9cfa..21b0e10 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) +## Workload server connections -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..7ee2f1f 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 @@ -175,13 +175,14 @@ metadata: name: default namespace: default spec: - subnets: # List of the subnets that VPCs can pick their subnets from + subnets: # List of prefixes that VPCs can pick their subnets from - 10.10.0.0/16 ``` ## 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