Merge pull request #569 from gibmat/tutorial-network-roles-vlan

Add VLAN tagging tutorial

Author: stgraber

doc/reference/system/network.md

@@ -10,6 +10,17 @@ Be aware that changing network configuration may result in a brief period of tim
 IncusOS automatically configures each interface and bond as a network bridge. This allows for easy out-of-the-box configuration of bridged NICs for containers and virtual machines.
 ```
 
+## Roles
+
+Each interface, bond or VLAN can be assigned one or more _roles_, which are used by IncusOS to control how the network device is used:
+
+* `cluster`: The device is used for internal cluster communication
+* `instances`: The device should be made available for use by Incus containers or virtual machines
+* `management`: The device is used for management
+* `storage`: The device is used for network-attached storage connectivity
+
+By default, the `cluster` and `management` roles will be assigned.
+
 ## Configuration options
 
 Interfaces, bonds, and VLANs have a significant number of fields, which are largely self-descriptive and can be viewed in the [API definition](https://github.com/lxc/incus-os/blob/main/incus-osd/api/system_network.go).

doc/tutorials.md

@@ -4,5 +4,6 @@ The following tutorials demonstrate various ways to configure and use IncusOS.
 ```{toctree}
 :maxdepth: 1
 Expanding the "local" storage pool </tutorials/storage-expand-local-pool>
-Network: Directly attach instances to host network </tutorials/network-direct-attach>
+Directly attaching instances to host network </tutorials/network-direct-attach>
+Applying VLAN tagging to physical networks </tutorials/network-vlan-tagging>
 ```

doc/tutorials/network-direct-attach.md

@@ -11,7 +11,7 @@ gibmat@futurfusion:~$ incus network list
 +----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+
 ```
 
-However, sometimes you may want to attach a container or virtual machine directly to the host's network. This is easily accomplished by assigning the `instances` role to the appropriate interfaces or bonds.
+However, sometimes you may want to attach a container or virtual machine directly to the host's network. This is easily accomplished by assigning the `instances` [role](../reference/system/network.md) to the appropriate interfaces or bonds.
 
 First, get the current IncusOS network configuration:
 
@@ -81,6 +81,20 @@ gibmat@futurfusion:~$ incus network list
 +----------+--------+---------+----------------+---------------------------+----------------------------+---------+---------+
 ```
 
+Create a managed network using that network interface:
+
+```
+gibmat@futurfusion:~$ incus network create enp5s0 parent=enp5s0 --type=physical
+gibmat@futurfusion:~$ incus network list
++----------+----------+---------+----------------+---------------------------+----------------------------+---------+---------+
+|   NAME   |   TYPE   | MANAGED |      IPV4      |           IPV6            |        DESCRIPTION         | USED BY |  STATE  |
++----------+----------+---------+----------------+---------------------------+----------------------------+---------+---------+
+| enp5s0   | physical | YES     |                |                           |                            | 0       | CREATED |
++----------+----------+---------+----------------+---------------------------+----------------------------+---------+---------+
+| incusbr0 | bridge   | YES     | 10.89.179.1/24 | fd42:e1a1:408f:710a::1/64 | Local network bridge (NAT) | 1       | CREATED |
++----------+----------+---------+----------------+---------------------------+----------------------------+---------+---------+
+```
+
 Now, you can configure an instance to directly connect to the host's physical network:
 
 ```
@@ -97,3 +111,9 @@ gibmat@futurfusion:~$ incus list
 | debian-nat    | RUNNING | 10.89.179.217 (eth0)  | fd42:e1a1:408f:710a:1266:6aff:fef6:4995 (eth0) | CONTAINER | 0         |
 +---------------+---------+-----------------------+------------------------------------------------+-----------+-----------+
 ```
+
+You can also make this network the default for all instances:
+
+```
+gibmat@futurfusion:~$ incus profile device set default eth0 network=enp5s0
+```

doc/tutorials/network-vlan-tagging.md

@@ -0,0 +1,73 @@
+# Applying VLAN tagging to physical networks
+
+IncusOS can assign automatic VLAN tagging for one or more VLANs to any configured interface or bond.
+
+This tutorial will assume the network interface is named `enp5s0` and the VLAN ID we want to set is `1234`.
+
+To assign the VLAN tagging, we need to make sure the interface is assigned both the `instances` [role](../reference/system/network.md) and that the `vlan_tags` property consists of a list of desired VLAN ID(s). This can be done by running `incus admin os system edit network` and edit the configuration like follows:
+
+```
+config:
+  interfaces:
+  - addresses:
+    - dhcp4
+    - slaac
+    hwaddr: 10:66:6a:d2:32:18
+    lldp: false
+    name: enp5s0
+    required_for_online: "no"
+    roles:
+    - instances
+    vlan_tags:
+    - 1234
+```
+
+After the configuration change is applied, a new unmanaged bridge will appear:
+
+```
+gibmat@futurfusion:~$ incus network list
++----------+--------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+|   NAME   |  TYPE  | MANAGED |      IPV4       |           IPV6            |        DESCRIPTION         | USED BY |  STATE  |
++----------+--------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+| enp5s0   | bridge | NO      |                 |                           |                            | 0       |         |
++----------+--------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+| incusbr0 | bridge | YES     | 10.148.244.1/24 | fd42:15d0:aec3:c78d::1/64 | Local network bridge (NAT) | 1       | CREATED |
++----------+--------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+
+```
+
+Create a managed network for VLAN `1234`:
+
+```
+gibmat@futurfusion:~$ incus network create enp5s0.1234 parent=enp5s0 vlan=1234 --type=physical
+Network enp5s0.1234 created
+gibmat@futurfusion:~$ incus network list
++-------------+----------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+|    NAME     |   TYPE   | MANAGED |      IPV4       |           IPV6            |        DESCRIPTION         | USED BY |  STATE  |
++-------------+----------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+| enp5s0      | bridge   | NO      |                 |                           |                            | 1       |         |
++-------------+----------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+| enp5s0.1234 | physical | YES     |                 |                           |                            | 0       | CREATED |
++-------------+----------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+| incusbr0    | bridge   | YES     | 10.148.244.1/24 | fd42:15d0:aec3:c78d::1/64 | Local network bridge (NAT) | 1       | CREATED |
++-------------+----------+---------+-----------------+---------------------------+----------------------------+---------+---------+
+```
+
+Now, you can configure an instance to use VLAN `1234`:
+
+```
+gibmat@futurfusion:~$ incus launch images:debian/13 debian --network enp5s0.1234
+Launching debian
+gibmat@futurfusion:~$ incus list
++--------+---------+-----------------------+------------------------------------------------+-----------+-----------+
+|  NAME  |  STATE  |         IPV4          |                      IPV6                      |   TYPE    | SNAPSHOTS |
++--------+---------+-----------------------+------------------------------------------------+-----------+-----------+
+| debian | RUNNING | 10.234.136.199 (eth0) | fd42:3cfb:8972:3990:1266:6aff:fe71:14e0 (eth0) | CONTAINER | 0         |
++--------+---------+-----------------------+------------------------------------------------+-----------+-----------+
+```
+
+You can also make this network the default for all instances:
+
+```
+gibmat@futurfusion:~$ incus profile device set default eth0 network=enp5s0.1234
+```