Skip to content

Commit

Permalink
Misc. minor corrections.
Browse files Browse the repository at this point in the history
Including:

* Unified some formatting.
* removed spurious ```yaml that was being rendered.
* Fixed the definitions for VLANNamespace and IPv4Namespace, which
  were swapped.
  • Loading branch information
Fredi-raspall committed Sep 30, 2024
1 parent 4788715 commit 0d5e32d
Show file tree
Hide file tree
Showing 4 changed files with 36 additions and 35 deletions.
10 changes: 5 additions & 5 deletions docs/concepts/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
16 changes: 8 additions & 8 deletions docs/user-guide/connections.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
14 changes: 7 additions & 7 deletions docs/user-guide/devices.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
31 changes: 16 additions & 15 deletions docs/user-guide/vpcs.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down

0 comments on commit 0d5e32d

Please sign in to comment.