[pve-devel] [PATCH docs v3 13/13] ct: add OCI image docs

[Filip Schauer]

Signed-off-by: Filip Schauer <f.schauer at proxmox.com>
---
Introduced in v3

 pct.adoc | 72 +++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 64 insertions(+), 8 deletions(-)

diff --git a/pct.adoc b/pct.adoc
index 529b72f..b538f56 100644
--- a/pct.adoc
+++ b/pct.adoc
@@ -54,15 +54,22 @@ the cluster setup, and they can use the same network and storage resources as
 virtual machines. You can also use the {pve} firewall, or manage containers
 using the HA framework.
 
-Our primary goal is to offer an environment that provides the benefits of using a
-VM, but without the additional overhead. This means that Proxmox Containers can
-be categorized as ``System Containers'', rather than ``Application Containers''.
+Our primary goal has traditionally been to offer an environment that provides
+the benefits of using a VM, but without the additional overhead. This means that
+Proxmox Containers have been primarily categorized as ``System Containers''.
 
-NOTE: If you want to run application containers, for example, 'Docker' images, it
-is recommended that you run them inside a Proxmox QEMU VM. This will give you
-all the advantages of application containerization, while also providing the
-benefits that VMs offer, such as strong isolation from the host and the ability
-to live-migrate, which otherwise isn't possible with containers. 
+With the introduction of OCI (**O**pen **C**ontainer **I**nitiative) image support,
+Proxmox VE now also integrates ``Application Containers''. When creating a
+container from an OCI image, the image is automatically converted to the
+LXC stack that Proxmox VE uses.
+
+This approach allows users to benefit from a wide ecosystem of pre-packaged
+applications while retaining the robust management features of Proxmox VE.
+
+While running lightweight ``Application Containers'' directly offers significant
+advantages over a full VM, for use cases demanding maximum isolation and
+the ability to live-migrate, nesting containers inside a Proxmox QEMU VM remains
+a recommended practice.
 
 
 Technology Overview
@@ -256,6 +263,12 @@ Container Images
 
 Container images, sometimes also referred to as ``templates'' or
 ``appliances'', are `tar` archives which contain everything to run a container.
+Proxmox VE can utilize two main types of images: *System Container Templates*
+for creating full virtual environments, and *Application Container Images* based
+on the OCI standard for running specific applications.
+
+System Container Templates
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 {pve} itself provides a variety of basic templates for the
 xref:pct_supported_distributions[most common Linux distributions].  They can be
@@ -336,6 +349,49 @@ delete that image later with:
 # pveam remove local:vztmpl/debian-10.0-standard_10.0-1_amd64.tar.gz
 ----
 
+Open Container Initiative (OCI) Images (Experimental)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Proxmox VE can also use OCI images to create containers. This makes it easy to
+run pre-packaged applications. A container created from an OCI image still uses
+the existing LXC framework.
+
+Obtaining OCI Images
+~~~~~~~~~~~~~~~~~~~~
+
+An OCI image can be pulled from a registry and saved as a `tar` archive. You can
+use tools like `docker`, `podman`, or `skopeo` for this. For example, to obtain
+the Apache HTTP Server (httpd) image from Docker Hub:
+
+Using Docker:
+
+----
+# docker pull httpd
+# docker save httpd > httpd.tar
+----
+
+Using Podman:
+
+When using Podman, the archive format must be explicitly specified as
+`oci-archive`.
+
+----
+# podman pull httpd
+# podman save --format=oci-archive httpd > httpd.tar
+----
+
+Using skopeo:
+
+----
+# skopeo copy docker://httpd:latest oci-archive:httpd.tar:latest
+----
+
+The resulting `httpd.tar` archive is an OCI image. It can be uploaded to a
+Proxmox VE storage that supports container templates via the *Upload* button in
+the storage content view of the web interface.
+
+Once the template is on a storage, you can create the container with
+`pct create` or use the wizard in the web interface.
 
 [[pct_settings]]
 Container Settings
-- 
2.47.2