Merge pull request #1331 from stgraber/doc

Add some application container documentation

doc/.wordlist.txt

@@ -134,6 +134,7 @@ kbit
 KiB
 kibi
 Kibit
+Kubernetes
 KVM
 lookups
 Loongarch

doc/explanation/instances.md

@@ -3,17 +3,40 @@
 
 Incus supports the following types of instances:
 
-Containers
-: Containers are the default type for instances.
-  They are currently the most complete implementation of Incus instances and support more features than virtual machines.
+Systems Containers
+: System containers run full Linux distributions using a shared kernel
+  Those containers run a full Linux distribution, very similar to a virtual machine but sharing kernel with the host system.
 
-  Containers are implemented through the use of `liblxc` (LXC).
+  They have an extremely low overhead, can be packed very densely and
+  generally provide a near identical experience to virtual machines
+  without the required hardware support and overhead.
+
+  System containers are implemented through the use of `liblxc` (LXC).
+
+Application containers
+: Application containers run a single application through a pre-built image
+  Those kind of containers got popularized by the likes of Docker and Kubernetes.
+
+  Rather than provide a pristine Linux environment on top of which software needs to be installed,
+  they instead come with a pre-installed and mostly pre-configured piece of software.
+
+  Incus can consume application container images from any OCI-compatible image registry (e.g. the Docker Hub).
+
+  Application containers are implemented through the use of `liblxc` (LXC) with help from `umoci` and `skopeo`.
 
 Virtual machines
-: {abbr}`Virtual machines (VMs)` are natively supported since version 4.0 of Incus.
-  Thanks to a built-in agent, they can be used almost like containers.
+: {abbr}`Virtual machines (VMs)` are a full virtualized system
+  Virtual machines are also natively supported by Incus and provide an alternative to system containers.
+
+  Not everything can run properly in containers. Anything that requires
+  a different kernel or its own kernel modules should be run in a virtual
+  machine instead.
+
+  Similarly, some kind of device pass-through, such as full PCI devices will only work properly with virtual machines.
+
+  To keep the user experience consistent, a built-in agent is provided by Incus to allow for interactive command execution and file transfers.
 
-  Incus uses `qemu` to provide the VM functionality.
+  Virtual machines are implemented through the use of QEMU.
 
   ```{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.

doc/howto/instances_create.md

@@ -48,12 +48,22 @@ Check the contents of an existing instance configuration ([`incus config show <i
 
 The following examples use [`incus launch`](incus_launch.md), but you can use [`incus init`](incus_create.md) in the same way.
 
-### Launch a container
+### Launch a system container
 
-To launch a container with an Ubuntu 22.04 image from the `images` server using the instance name `ubuntu-container`, enter the following command:
+To launch a system container with an Ubuntu 22.04 image from the `images` server using the instance name `ubuntu-container`, enter the following command:
 
     incus launch images:ubuntu/22.04 ubuntu-container
 
+### Launch an application container
+
+To launch an application (OCI) container, you first need to add an image registry:
+
+    incus remote add oci-docker https://docker.io --protocol=oci
+
+And then can launch a container from one of its images:
+
+    incus launch oci-docker:hello-world --ephemeral --console
+
 ### Launch a virtual machine
 
 To launch a virtual machine with an Ubuntu 22.04 image from the `images` server using the instance name `ubuntu-vm`, enter the following command: