Merge pull request #13182 from ru-fu/LXD-535-explanation-docs

doc/explanation: reorder pages and update the landing page

doc/custom_conf.py

@@ -134,6 +134,7 @@
 redirects = {
     'howto/instances_snapshots/index': '../instances_backup/',
     'reference/network_external/index': '../networks/',
+    'explanation/containers_and_vms/index': '../instances/'
 }
 
 ############################################################

doc/explanation/index.md

@@ -3,20 +3,53 @@
 
 The explanatory guides in this section introduce you to the concepts used in LXD and help you understand how things fit together.
 
+## Important concepts
+
+Before you start working with LXD, you need to be familiar with some important concepts about LXD and the instance types it provides.
+
+```{toctree}
+:titlesonly:
+
+/explanation/lxd_lxc
+/explanation/instances
+```
+
+## Entities in LXD
+
+When working with LXD, you should have a basic understanding of the different entities that are used in LXD.
+See the {ref}`howtos` for instructions on how to work with these entities, and the following guides to understand the concepts behind them.
+
+```{toctree}
+:titlesonly:
+
+/image-handling
+About storage </explanation/storage>
+/explanation/networks
+/database
+```
+
+## Access management
+
+In LXD, access to the API is controlled through TLS or OpenID Connect authentication.
+When using OpenID Connect, you can grant permissions to access specific entities to different clients.
+You can also restrict access to LXD entities by confining them to specific projects.
+
 ```{toctree}
 :titlesonly:
 
 About authentication </authentication>
 About authorization </explanation/authorization>
+/explanation/projects
+```
+
+## Production setup
+
+When you're ready to move your LXD setup to production, you should read up on the concepts that are important for providing a scalable, reliable, and secure environment.
+
+```{toctree}
+:titlesonly:
+
 /explanation/clustering
-/explanation/containers_and_vms
-/image-handling
-/explanation/instances
-/explanation/lxd_lxc
-/explanation/networks
 /explanation/performance_tuning
-/explanation/projects
 /explanation/security
-About storage </explanation/storage>
-/database
 ```

doc/explanation/instances.md

@@ -3,8 +3,33 @@ discourse: 8767,7519,9281
 relatedlinks: '[LXD virtual machines: an overview](https://ubuntu.com/blog/lxd-virtual-machines-an-overview)'
 ---
 
+(containers-and-vms)=
+# About containers and VMs
+
+LXD provides support for two different types of {ref}`instances <expl-instances>`: *system containers* and *virtual machines*.
+
+When running a system container, LXD simulates a virtual version of a full operating system. To do this, it uses the functionality provided by the kernel running on the host system.
+
+When running a virtual machine, LXD uses the hardware of the host system, but the kernel is provided by the virtual machine. Therefore, virtual machines can be used to run, for example, a different operating system.
+
+## Application containers vs. system containers
+
+Application containers (as provided by, for example, Docker) package a single process or application. System containers, on the other hand, simulate a full operating system and let you run multiple processes at the same time.
+
+Therefore, application containers are suitable to provide separate components, while system containers provide a full solution of libraries, applications, databases and so on. In addition, you can use system containers to create different user spaces and isolate all processes belonging to each user space, which is not what application containers are intended for.
+
+![Application and system containers](/images/application-vs-system-containers.svg "Application and system containers")
+
+## Virtual machines vs. system containers
+
+Virtual machines emulate a physical machine, using the hardware of the host system from a full and completely isolated operating system. System containers, on the other hand, use the OS kernel of the host system instead of creating their own environment. If you run several system containers, they all share the same kernel, which makes them faster and more light-weight than virtual machines.
+
+With LXD, you can create both system containers and virtual machines. You should use a system container to leverage the smaller size and increased performance if all functionality you require is compatible with the kernel of your host operating system. If you need functionality that is not supported by the OS kernel of your host system or you want to run a completely different OS, use a virtual machine.
+
+![Virtual machines and system containers](/images/virtual-machines-vs-system-containers.svg "Virtual machines and system containers")
+
 (expl-instances)=
-# About instances
+## Instance types in LXD
 
 LXD supports the following types of instances:
 
@@ -23,15 +48,11 @@ Virtual machines
   ```{note}
   Currently, virtual machines support fewer features than containers, but the plan is to support the same set of features for both instance types in the future.
 
-  To see which features are available for virtual machines, check the condition column in the {ref}`instance-options` documentation.
+  To see which features are available for virtual machines, check the condition field in the {ref}`instance-options` documentation.
   ```
 
 ## Related topics
 
-Explanation:
-
-- {ref}`containers-and-vms`
-
 {{instances_how}}
 
 {{instances_ref}}

doc/getting_started.md

@@ -43,7 +43,7 @@ You can also find a series of demos and tutorials on YouTube:
 :maxdepth: 1
 
 :topical:/tutorial/first_steps
-:topical:/explanation/containers_and_vms
+:topical:/explanation/instances
 :topical:/requirements
 :topical:Install LXD </installing>
 :topical:Initialize LXD </howto/initialize>