Merge pull request #11136 from ru-fu/LXD-268-instances-doc

tomponline · web-flow · commit e385e26f0464 · 2022-11-28T12:40:39.000Z
doc/instances: clean up devices overview section
diff --git a/doc/explanation/instance_config.md b/doc/explanation/instance_config.md
@@ -21,14 +21,26 @@ Instance options
 
   In the YAML configuration, options are located under the `config` entry.
 
-  See {ref}`instance-options` for a reference of available instance options.
+  See {ref}`instance-options` for a reference of available instance options, and {ref}`instances-configure-options` for instructions on how to configure the options.
+
+Instance devices
+: Instance devices are attached to an instance.
+  They include, for example, network interfaces, mount points, USB and GPU devices.
+  Devices are usually added after an instance is created with the `lxc config device add` command, but they can also be added to a profile or a YAML configuration file that is used to create an instance.
+
+  Each type of device has its own specific set of options, referred to as *instance device options*.
+
+  In the YAML configuration, devices are located under the `devices` entry.
+
+  See {ref}`devices` for a reference of available devices and the corresponding instance device options, and {ref}`instances-configure-devices` for instructions on how to add and configure instance devices.
 
 ```{toctree}
 :maxdepth: 1
 :hidden:
 
 ../reference/instance_properties.md
 ../reference/instance_options.md
+../reference/devices.md
 Override QEMU configuration <../howto/instance_qemu_config.md>
 ../reference/instance_units.md
 ```
diff --git a/doc/howto/instances_configure.md b/doc/howto/instances_configure.md
@@ -9,6 +9,7 @@ See the following sections for instructions.
 To store and reuse different instance configurations, use {ref}`profiles <profiles>`.
 ```
 
+(instances-configure-options)=
 ## Configure instance options
 
 You can specify instance options when you {ref}`create an instance <instances-create>`.
@@ -31,15 +32,29 @@ Others are updated only when the instance is restarted.
 See the "Live update" column in the {ref}`instance-options` table for information about which options are applied immediately while the instance is running.
 ```
 
+(instances-configure-devices)=
 ## Configure devices
 
 To add and configure an instance device for your instance, use the `lxc config device add` command.
-Specify the instance name, a device name, the device type and maybe device options (depending on the {ref}`device type <device-types>`):
+Generally, devices can be added or removed for a container while it is running.
+VMs support hotplugging for some device types, but not all.
+
+Specify the instance name, a device name, the device type and maybe device options (depending on the {ref}`device type <devices>`):
 
     lxc config device add <instance_name> <device_name> <device_type> <device_option_key>=<device_option_value> <device_option_key>=<device_option_value> ...
 
 See {ref}`devices` for a list of available device types and their options.
 
+```{note}
+Every device entry is identified by a name unique to the instance.
+
+Devices from profiles are applied to the instance in the order in which the profiles are assigned to the instance.
+Devices defined directly in the instance configuration are applied last.
+At each stage, if a device with the same name already exists from an earlier stage, the whole device entry is overridden by the latest definition.
+
+Device names are limited to a maximum of 64 characters.
+```
+
 For example, to add the storage at `/share/c1` on the host system to your instance at path `/opt`, enter the following command:
 
     lxc config device add my-container disk-storage-device disk source=/share/c1 path=/opt
@@ -48,6 +63,9 @@ To configure instance device options for a device that you have added earlier, u
 
     lxc config device set <instance_name> <device_name> <device_option_key>=<device_option_value> <device_option_key>=<device_option_value> ...
 
+To remove a device, use the `lxc config device remove` command.
+See `lxc config device --help` for a full list of available commands.
+
 ## Display instance configuration
 
 To display the current configuration of your instance, including writable instance properties, instance options, devices and device options, enter the following command:
diff --git a/doc/instances.md b/doc/instances.md
@@ -13,5 +13,4 @@ Run commands <instance-exec.md>
 Access the console <howto/instances_console.md>
 Access files <howto/instances_access_files.md>
 explanation/instance_config.md
-explanation/devices.md
 ```
diff --git a/doc/profiles.md b/doc/profiles.md
@@ -35,6 +35,7 @@ Enter the following command to create an empty profile:
 
     lxc profile create <profile_name>
 
+(profiles-edit)=
 ## Edit a profile
 
 You can either set specific configuration options for a profile or edit the full profile in YAML format.
@@ -47,7 +48,7 @@ Specify the profile name and the key and value of the instance option:
     lxc profile set <profile_name> <option_key>=<option_value> <option_key>=<option_value> ...
 
 To add and configure an instance device for your profile, use the `lxc profile device add` command.
-Specify the profile name, a device name, the device type and maybe device options (depending on the {ref}`device type <device-types>`):
+Specify the profile name, a device name, the device type and maybe device options (depending on the {ref}`device type <devices>`):
 
     lxc profile device add <instance_name> <device_name> <device_type> <device_option_key>=<device_option_value> <device_option_key>=<device_option_value> ...
 
diff --git a/doc/reference/devices.md b/doc/reference/devices.md
@@ -1,61 +1,11 @@
 (devices)=
 # Devices
 
-Devices are attached to an instance.
+Devices are attached to an instance (see {ref}`instances-configure-devices`) or to a profile (see {ref}`profiles-edit`).
+
 They include, for example, network interfaces, mount points, USB and GPU devices.
 These devices can have instance device options, depending on the type of the instance device.
 
-## Standard devices
-
-LXD will always provide the instance with the basic devices which are required
-for a standard POSIX system to work. These aren't visible in instance or
-profile configuration and may not be overridden.
-
-Those include:
-
-- `/dev/null` (character device)
-- `/dev/zero` (character device)
-- `/dev/full` (character device)
-- `/dev/console` (character device)
-- `/dev/tty` (character device)
-- `/dev/random` (character device)
-- `/dev/urandom` (character device)
-- `/dev/net/tun` (character device)
-- `/dev/fuse` (character device)
-- `lo` (network interface)
-
-Anything else has to be defined in the instance configuration or in one of its
-profiles. The default profile will typically contain a network interface to
-become `eth0` in the instance.
-
-## How to add devices
-
-To add extra devices to an instance, device entries can be added directly to an
-instance, or to a profile.
-
-Devices may be added or removed while the instance is running.
-
-Every device entry is identified by a unique name. If the same name is used in
-a subsequent profile or in the instance's own configuration, the whole entry
-is overridden by the new definition.
-
-Device names are limited to a maximum of 64 characters.
-
-Device entries are added to an instance through:
-
-```bash
-lxc config device add <instance> <name> <type> [key=value]...
-```
-
-or to a profile with:
-
-```bash
-lxc profile device add <profile> <name> <type> [key=value]...
-```
-
-(device-types)=
-## Device types
-
 LXD supports the following device types:
 
 | ID (database) | Name                                   | Condition | Description                     |
@@ -73,10 +23,13 @@ LXD supports the following device types:
 | 10            | [`tpm`](devices-tpm)                   | -         | TPM device                      |
 | 11            | [`pci`](devices-pci)                   | VM        | PCI device                      |
 
+Each instance comes with a set of {ref}`standard-devices`.
+
 ```{toctree}
 :maxdepth: 1
 :hidden:
 
+../reference/standard_devices.md
 ../reference/devices_none.md
 ../reference/devices_nic.md
 ../reference/devices_disk.md
diff --git a/doc/reference/devices_disk.md b/doc/reference/devices_disk.md
@@ -1,7 +1,7 @@
 (devices-disk)=
 # Type: `disk`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Disk entries are essentially mount points inside the instance. They can
 either be a bind-mount of an existing file or directory on the host, or
diff --git a/doc/reference/devices_gpu.md b/doc/reference/devices_gpu.md
@@ -56,7 +56,7 @@ Key         | Type      | Default           | Required  | Description
 
 ## `gpu`: `mig`
 
-Supported instance types: container
+Supported instance types: container (does not support hotplugging)
 
 Creates and passes through a MIG compute instance. This currently requires NVIDIA MIG instances to be pre-created.
 
diff --git a/doc/reference/devices_nic.md b/doc/reference/devices_nic.md
@@ -39,7 +39,7 @@ The following NICs can be specified using only the `nictype` property:
 (instance_device_type_nic_bridged)=
 ## `nic`: `bridged`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`, `network`
 
@@ -76,7 +76,7 @@ Key                      | Type    | Default           | Required | Managed | De
 
 ## `nic`: `macvlan`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`, `network`
 
@@ -99,7 +99,7 @@ Key                     | Type    | Default           | Required | Managed | Des
 
 ## `nic`: `sriov`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`, `network`
 
@@ -186,7 +186,7 @@ ip link set enp9s0f0np0 up
 
 ## `nic`: `physical`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`
 
@@ -208,7 +208,7 @@ Key                     | Type    | Default           | Required | Description
 
 ## `nic`: `ipvlan`
 
-Supported instance types: container
+Supported instance types: container (does not support hotplugging)
 
 Selected using: `nictype`
 
@@ -255,7 +255,7 @@ Key                     | Type    | Default            | Required | Description
 
 ## `nic`: `p2p`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`
 
@@ -278,7 +278,7 @@ Key                     | Type    | Default           | Required | Description
 
 ## `nic`: `routed`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 Selected using: `nictype`
 
diff --git a/doc/reference/devices_proxy.md b/doc/reference/devices_proxy.md
@@ -5,7 +5,7 @@ discourse: 8355
 (devices-proxy)=
 # Type: `proxy`
 
-Supported instance types: container (`nat` and non-`nat` modes), VM (`nat` mode only)
+Supported instance types: container (`nat` and non-`nat` modes), VM (`nat` mode only, supports hotplugging)
 
 Proxy devices allow forwarding network connections between host and instance.
 This makes it possible to forward traffic hitting one of the host's
diff --git a/doc/reference/devices_usb.md b/doc/reference/devices_usb.md
@@ -1,7 +1,7 @@
 (devices-usb)=
 # Type: `usb`
 
-Supported instance types: container, VM
+Supported instance types: container, VM (supports hotplugging)
 
 USB device entries simply make the requested USB device appear in the
 instance.
diff --git a/doc/reference/standard_devices.md b/doc/reference/standard_devices.md
@@ -0,0 +1,23 @@
+(standard-devices)=
+# Standard devices
+
+LXD provides each instance with the basic devices that are required for a standard POSIX system to work.
+These devices aren't visible in the instance or profile configuration, and they may not be overridden.
+
+The standard devices are:
+
+| Device         | Type of device    |
+|:---------------|:------------------|
+| `/dev/null`    | Character device  |
+| `/dev/zero`    | Character device  |
+| `/dev/full`    | Character device  |
+| `/dev/console` | Character device  |
+| `/dev/tty`     | Character device  |
+| `/dev/random`  | Character device  |
+| `/dev/urandom` | Character device  |
+| `/dev/net/tun` | Character device  |
+| `/dev/fuse`    | Character device  |
+| `lo`           | Network interface |
+
+Any other devices must be defined in the instance configuration or in one of the profiles used by the instance.
+The default profile typically contains a network interface that becomes `eth0` in the instance.
