[pve-devel] [PATCH docs] pve-network: add short section explaining Open vSwitch

[Aaron Lauterer]

Some notes from my side, changing sentence structure to put the 
important parts to the beginning and using a more active voice. Some 
typos and missed use of {pve} got changed as well.

More inline :)

On 8/27/19 12:27 PM, Christian Ebner wrote:
> Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
> ---
>   pve-network.adoc | 140 ++++++++++++++++++++++++++++++++++++++++++++++-
>   1 file changed, 139 insertions(+), 1 deletion(-)
> 
> diff --git a/pve-network.adoc b/pve-network.adoc
> index b2dae97..e8f17af 100644
> --- a/pve-network.adoc
> +++ b/pve-network.adoc
> @@ -489,7 +489,145 @@ iface vmbr0 inet manual
>   
>   ----
>   
> +Open vSwitch
> +~~~~~~~~~~~~
> +
> +https://www.openvswitch.org/[Open vSwitch (OVS)] is a "multilayer virtual switch
> +designed to enable network automation through programmatic extension, while still
> +supporting standard management interfaces and protocols". It is specifically
> +tailored to function with virtualized environments.
> +OVS is an alternative to Linux native bridges, bonds and VLAN interfaces and
> +should never be mixed with these as this can cause problems and loss of
> +connectivity.
> +
> +Installation
> +^^^^^^^^^^^^
> +
> +In order to use and configure Open vSwitch (OvS) in {pve}, the
> +'openvswitch-switch' package from the Proxmox VE package repositories has to be
> +installed:

In order to use and configure Open vSwitch (OVS) in {pve}, install the 
'openvswitch-switch' package from the {pve} package repositories:

# active voice

> +
> +----
> +# apt-get install openvswitch-switch
> +----
> +
> +Configuration
> +^^^^^^^^^^^^^
> +
> +OVS configuration is easily performed via the web interface of the node under
> +`System -> Network`.

You can configure OVS easily via the web-based interface under `System 
-> Network`.

# active

> +From there it is possible to create OVS brides, OVS bonds or an OVS internal
> +ports.

It is possible...

# reduce clutter

> +Advanced configuration is performed by editing `/etc/network/interfaces`,

For more advanced configurations edit the file ....

# active voice

> +see the https://pve.proxmox.com/wiki/Open_vSwitch[Open vSwitch wiki page] for
> +further details.
> +
> +OVS Bridge
> +^^^^^^^^^^
> +
> +Just like a Linux virtual bridge, this will create a new OVS virtual bridge,
> +allowing to attach raw ethernet devices and virtual interfaces such as OVS bonds
> +or OVS IntPorts.

# remove the whole sentence? or phrase it differently? something like 
the following?

The OVS virtual bridge is the base to which raw ethernet devices and 
virtual interfaces such as ... can be attached to.

# should we call it "is the switch to"? sounds weird though.

> +On creation, you can directly assing raw ethernet devices to attatch to the > +bridge ports and assing an IP address to the bridge.

On creation you can define the raw ethernet devices attached to the OVS 
bridge in the 'bridge_ports' field. You can configure IP addresses and 
gateways on the bridge if needed.

# no comma? phrase it a bit differently for better understanding. though 
I am not really happy about my suggestion either.

> +In contrast to Linux virtual bridges, OVS bridges can carry multiple VLANs over
> +a sinlge bridge.

# this is not true. by now Linux bridges can be set to VLAN aware and 
thus reduce the use cases for the OVS quite a bit.

> +
> +.Example: A simple OVS bridge setup with a single interface
> +----
> +allow-vmbr0 eth0
> +iface eth0 inet manual
> +        ovs_type OVSPort
> +        ovs_bridge vmbr0
> +
> +auto vmbr0
> +iface vmbr0 inet manual
> +        ovs_type OVSBridge
> +        ovs_ports eth0
> +----
> +
> +OVS Bond
> +^^^^^^^^
> +
> +Bonds are used to join two or more network interfaces (slaves) to act as a single
> +unit in order to increase data throughput and to provide redundancy in case one

Bonds are used to join two or more network interfaces (slaves) together 
to act as a single unit. This helps to increase data throughput and can 
provide redundancy if one of the physical links fails.

# split it into smaller sentences

> +of the links fails. Bonds must refer to raw ethernet devices (for example eth0,
> +eth1).
> +
> +The following bond modes can be set in the web interface:
> +
> +* active-backup: This will configure an active/standby failover mode. All of the
> +traffic is send over the active interface as long as it is available, on failure
> +the standby interface is used.
> +
> +* balance-slb: Source load balancing or SLB bonding will divide traffic based on
> +the ethernet source address and VLAN tag. It assigns each source MAC+VLAN to a
> +link.

Each source MAC+VLAN combination is assigned to one link.

> +
> +* LACP (balance-slb): This will configure balance-slb with LACP set to active.
> +
> +* LACP (balance-tcp): This will perform load balancing with layer 2 to layer 4
> +data taken into consideration with LACP set to active.
> +
> +NOTE: The use of LACP for link aggregation is recommended when creating a bond, but
> +requires the switch on the other end to support this.

... but requires support from the switches on the other end.

> +
> +For further details refere to the

refer

# typo

> +http://docs.openvswitch.org/en/latest/topics/bonding/[corresponding section in
> +the Open vSwitch documentation.]
> +
> +.Example: A simple OVS bond configuration
> +----
> +allow-vmbr0 bond0
> +iface bond0 inet manual
> +    ovs_bonds eth0 eth1
> +    ovs_type OVSBond
> +    ovs_bridge vmbr0
> +    ovs_options bond_mode=balance-tcp lacp=active
> +
> +auto vmbr0
> +iface vmbr0 inet manual
> +        ovs_type OVSBridge
> +        ovs_ports bond0
> +----
> +
> +OVS IntPort
> +^^^^^^^^^^^
> +
> +The creation of an OVS IntPort is neccessary in order for the host to connect to
> +a VLAN on the bridge.

An OVS IntPort is necessary for the host to connect to a VLAN on the bridge.

> +This creates a virtual interface for the specified VLAN to which then an IP
> +address can be assigned.

... VLAN for which an IP address can be configured.

> +The so created ports must also show up in the corresponding bridge definition and
> +have to be prefixed with the `allow-$bridge $iface`.

These IntPorts must be configured in the corresponding bridge definition 
and need to be prefixed with `allow-<bridge> <interface>.

# we don't have a standard way defined for placeholders AFAIK. but I 
would opt for either <placeholder> oder PLACEHOLDER. Those should be 
easier to notice as such by the target audience.

> +
> +.Example: A OVS IntPort with assigned IP address

Example: An OVD IntPort ('vlan10') with an IP address assigned:

# a/an and add the name of the interface to know what to look out for

> +----
> +allow-vmbr0 bond0
> +iface bond0 inet manual
> +    ovs_bonds eth0 eth1
> +    ovs_type OVSBond
> +    ovs_bridge vmbr0
> +    ovs_options tag=10 bond_mode=balance-tcp lacp=active
> +
> +allow-vmbr0 vlan10
> +iface vlan10 inet static
> +    address 10.0.0.10
> +    netmask 24
> +    ovs_type OVSIntPort
> +    ovs_bridge vmbr0
> +    ovs_options tag=10
> +
> +auto vmbr0
> +iface vmbr0 inet manual
> +        ovs_type OVSBridge
> +        ovs_ports bond0 vlan10
> +----
> +
> +For further details see http://docs.openvswitch.org/en/latest/[the Open vSwitch documentation] and
> +the https://pve.proxmox.com/wiki/Open_vSwitch[Open vSwitch wiki page].
> +
>   ////
>   TODO: explain IPv6 support?
> -TODO: explain OVS
> +
>   ////
>