githedgehog · Frostman · Oct 8, 2024 · Sep 30, 2024
@@ -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

@@ -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
@@ -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.
 

@@ -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

@@ -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

@@ -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.<subnet>.dhcp.relay`, additional information is
+### Third-party DHCP server configuration
+
+In case you use a third-party DHCP server, by configuring `spec.subnets.<subnet>.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