feat(docs): Add public documentation for LXD and OpenStack images

.custom_wordlist.txt

@@ -205,6 +205,7 @@ OpenSCAP
 OpenShift
 OpenSSH
 openssl
+OpenStack
 OVAs
 OVF
 OwnerId

public-images/index.rst

@@ -23,9 +23,9 @@ In this documentation
 .. grid:: 1 1 2 2
    :padding: 0
 
-   .. grid-item:: :doc:`Vagrant - An explanation <public-images-explanation/vagrant>`
+   .. grid-item:: :doc:`Explanation <public-images-explanation/index>`
 
-      **What are Vagrant boxes** and our support status for them.
+      **Discussion and clarification** of key topics related to our Public Images offerings.
 
    .. grid-item:: :doc:`Cloud image artefacts - A reference <public-images-reference/artefacts>`
 
@@ -53,9 +53,9 @@ suggestions, fixes and constructive feedback.
    :hidden:
    :maxdepth: 1
 
+   public-images-explanation/index
    public-images-how-to/index
    public-images-reference/artefacts
-   Vagrant - An explanation<public-images-explanation/vagrant>
    public-images-how-to/contribute-to-these-docs
 
 .. _Get support: https://ubuntu.com/cloud/public-cloud

public-images/public-images-explanation/index.rst

@@ -0,0 +1,16 @@
+.. _public-images-explanation:
+
+Explanation
+===========
+
+The explanatory guides provided are designed to provide a better understanding of Ubuntu cloud images and associated tooling.
+
+- :ref:`lxd-openstack-images`
+- :ref:`vagrant-explanation`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   LXD and OpenStack images<lxd-openstack-images>
+   Vagrant<vagrant>

public-images/public-images-explanation/lxd-openstack-images.rst

@@ -0,0 +1,210 @@
+.. _lxd-openstack-images:
+
+LXD and OpenStack images
+========================
+
+`LXD <https://canonical.com/lxd>`__ is an open-source tool for
+orchestrating virtual machines and system containers. It is image based,
+and provides support for a large number of distributions and
+architectures.
+
+`OpenStack <https://ubuntu.com/openstack>`__ is an
+open-source cloud platform designed to create and manage cloud
+resources. By aggregating physical resources such as distributed
+compute, network, and storage into a pool, OpenStack then allocates
+virtual resources on-demand to users out of this pool. It does not
+handle virtualisation itself, but acts as a wrapper that leverages
+existing virtualisation technologies.
+
+
+What are these images?
+----------------------
+
+Canonical provides cloud image artefacts on
+`cloud-images.ubuntu.com <https://cloud-images.ubuntu.com/>`__ that have
+been customised to run on public clouds, including LXD and OpenStack. To
+learn more about these artefacts and supported architectures, visit our
+Ubuntu cloud image artefacts documentation :doc:`here <../public-images-reference/artefacts>`.
+
+
+How do you access them?
+-----------------------
+
+Go to `cloud-images.ubuntu.com <https://cloud-images.ubuntu.com/>`__ and
+select a release. For the latest LTS release, Ubuntu 24.04 LTS Noble
+Numbat, you would navigate to ``noble > current``. Note that all artefacts are
+architecture specific, in the format
+``<release>-<type>-cloudimg-<architecture>-<artefact>``.
+
+LXD and OpenStack also have `Minimal Cloud
+Images <https://cloud-images.ubuntu.com/minimal/>`__:
+Ubuntu images that have a reduced runtime footprint, optimised kernel
+and boot process. They are smaller and boot faster, but are not designed
+for environments requiring human interaction or debugging.
+
+
+LXD images
+~~~~~~~~~~
+
+To import an image into LXD, you will need two artefacts:
+
+1. An LXD tarball:
+
+   - The :ref:`lxd-tarball-ref` artefact has the extension ``*.lxd.tar.xz``
+   - It contains the metadata needed by LXD to instantiate a container or virtual machine as well as a folder for any custom templates
+
+2. A file system for a container or a bootable disk image for a virtual
+   machine:
+
+   - The file system for a container can be either a 
+
+     * :ref:`root-tarball-ref` (``*-root.tar.xz``), or a 
+
+     * :ref:`squashfs-ref` (``*.squashfs``)
+
+   - The bootable disk image for a virtual machine is a :ref:`qcow-ref` image (``*.img``)
+
+The following are example commands to import LXD containers and virtual machines, respectively, based on downloaded Ubuntu 24.04 artefacts:
+
+.. code :: bash
+
+   lxc image import noble-server-cloudimg-amd64-lxd.tar.xz \
+      noble-server-cloudimg-amd64-root.tar.xz --alias noble_container
+
+.. code :: bash
+
+   lxc image import noble-server-cloudimg-amd64-lxd.tar.xz \
+      noble-server-cloudimg-amd64.img --alias noble_vm
+
+
+OpenStack images
+~~~~~~~~~~~~~~~~
+
+OpenStack uses QCOW images. Download the artefact for your chosen
+architecture with the ``*.img`` extension.
+
+Use the `OpenStack command-line
+client <https://docs.openstack.org/ocata/admin-guide/common/cli-install-openstack-command-line-clients.html>`__
+to interact with OpenStack. An example of uploading an image looks 
+something like this:
+
+.. code :: bash
+
+   openstack image create “Ubuntu-24.04” \
+      --file noble-server-cloudimg-amd64.img \
+      --disk-format qcow2 \
+      --container-format bare \
+      --public
+
+To learn more about managing images with OpenStack, you can read their
+documentation
+`here <https://docs.openstack.org/ocata/admin-guide/common/cli-manage-images.html#create-or-update-an-image-glance>`__.
+
+
+Configuration
+-------------
+
+Configuring an Ubuntu cloud image allows you to make changes that tailor
+the image to your specific use case. You can automate the creation of
+user accounts, configure SSH access, or install software before the
+instance starts.
+
+
+LXD images
+~~~~~~~~~~
+
+You can configure your cloud images in LXD either before you import them
+or after. Configuring your images before importing them is most commonly
+done by editing the ``metadata.yaml`` file contained in the LXD tarball.
+Configuring your images after importing them is done through the CLI.
+
+If you are interested in configuration of LXD containers rather than
+images, take a look at the Ubuntu Server documentation
+`here <https://documentation.ubuntu.com/server/how-to/containers/lxd-containers/>`__.
+
+
+Metadata
+^^^^^^^^
+
+LXD metadata is stored in the ``metadata.yaml`` file in the LXD tarball. This file contains all of 
+the information needed to run an image in LXD. To make changes to this file, you will have to:
+
+1. Uncompress the LXD tarball.
+2. Make modifications to the ``metadata.yaml`` file. See the `LXD image
+   format
+   documentation <https://documentation.ubuntu.com/lxd/en/latest/reference/image_format/#>`__
+   to learn more about image metadata and the templates you may wish to
+   modify.
+3. Compress the metadata and templates.
+
+This snippet from the `How to customise LXD image metadata for
+cloud-init <https://discourse.ubuntu.com/t/how-to-customize-lxd-image-metadata-for-cloud-init/25157>`__
+guide referenced below demonstrates a typical workflow:
+
+.. code :: bash
+
+   # Uncompress original LXD metadata
+   $ tar xf ${RELEASE}-server-cloudimg-amd64-lxd.tar.xz
+   # Add directives to create /etc/cloud/cloud.cfg.d/95-use-lxd.cfg
+   $ cat > templates/cloud-init-use-lxd.tpl <<EOF
+   # Added by LXD metadata.yaml
+   datasource_list: [ LXD, NoCloud ]
+   EOF
+   $ cat > add-lxd.yaml <<EOF
+       /etc/cloud/cloud.cfg.d/95-use-lxd.cfg:
+           when:
+               - create
+               - copy
+           template: cloud-init-use-lxd.tpl
+   EOF
+   $ cat add-lxd.yaml >> metadata.yaml
+   # Compress LXD metadata and templates
+   $ tar -czf ${RELEASE}-server-cloudimg-amd64-prefer-lxd.tar.xz metadata.yaml templates/
+
+
+Cloud-init
+^^^^^^^^^^
+
+`Cloud-init <https://cloudinit.readthedocs.io/en/latest/index.html>`__
+is used to initialise cloud instances on first boot. A detailed guide on
+customising LXD image metadata for ``cloud-init`` can be found
+`here <https://discourse.ubuntu.com/t/how-to-customize-lxd-image-metadata-for-cloud-init/25157>`__.
+If you want to configure ``cloud-init`` once an instance has been
+created (but not booted), refer to the LXD docs
+`here <https://documentation.ubuntu.com/lxd/en/latest/cloud-init/>`__.
+
+
+CLI
+^^^
+
+The `LXD documentation on
+images <https://documentation.ubuntu.com/lxd/en/latest/howto/images_manage/>`__
+has an extensive guide on managing images. Two of the most common use
+cases are to set individual properties or to edit all of the image
+properties.
+
+.. code :: bash
+
+   # set a specific image property
+   lxc image set-property <image_ID> <key> <value>
+
+
+.. code :: bash
+
+   # edit the full image properties
+   lxc image edit <image_ID>
+
+
+OpenStack images
+~~~~~~~~~~~~~~~~
+
+OpenStack has an extensive guide on `modifying
+images <https://docs.openstack.org/image-guide/modify-images.html>`__
+that is applicable to the QCOW images Ubuntu provides. It leverages ``libguestfs`` 
+`tools <https://libguestfs.org/>`__ in order to access and
+modify disk images. You can use the ``guestfish``
+`interactive shell <https://libguestfs.org/guestfish.1.html>`__ 
+— which exposes the full functionality of the ``guestfs`` API — or
+rely on the ``virt-*`` tools from ``libguestfs`` — like ``virt-cat`` for
+displaying files, ``virt-df`` for checking free space, and
+``virt-inspector`` for inspecting VM images — to perform specific tasks.

public-images/public-images-explanation/vagrant.rst

@@ -1,3 +1,5 @@
+.. _vagrant-explanation:
+
 Vagrant
 =======
 `Vagrant <https://www.vagrantup.com/>`_ is a multi-provider tool for building and managing virtual machines by HashiCorp. For more information, you can check out the `Vagrant documentation <https://developer.hashicorp.com/vagrant/intro>`_.

public-images/public-images-reference/artefacts.rst

@@ -1,3 +1,5 @@
+.. _uci-artefacts:
+
 Ubuntu cloud image artefacts
 ============================
 This document provides detailed information on various Ubuntu cloud image artefacts available on `cloud-images.ubuntu.com <https://cloud-images.ubuntu.com/>`_.
@@ -15,6 +17,8 @@ Architectures supported
 -  **riscv64:** 64-bit RISC-V architecture.
 -  **s390x:** IBM System z (s390x) architecture.
 
+.. _initrd-ref:
+
 Initial ramdisk (initrd)
 ~~~~~~~~~~~~~~~~~~~~~~~~
 .. list-table::
@@ -30,6 +34,8 @@ Initial ramdisk (initrd)
    * - Use cases
      - Initrds are used to ensure the kernel can boot by loading necessary drivers and modules before the root filesystem is mounted. This allows the support of diverse hardware and virtual environments, making them useful for cloud instance startup. In addition to extra driver support, early boot features such as labels for partition names and root encryption rely on features provided by the initrd.
 
+.. _kernel-image-ref:
+
 Linux kernel image
 ~~~~~~~~~~~~~~~~~~
 .. list-table::
@@ -45,6 +51,8 @@ Linux kernel image
    * - Use cases
      - The Linux kernel is the core component of the operating system. It handles essential functions such as process management, memory management and system calls. Kernel images may be customised for specific hardware configurations, leading to offerings for each supported architecture.
 
+.. _lxd-tarball-ref:
+
 LXD tarball
 ~~~~~~~~~~~
 .. list-table::
@@ -58,9 +66,9 @@ LXD tarball
    * - Format description
      - Tar archive compressed with XZ (LZMA2), containing an image suitable for LXD container deployment.
    * - Use cases
-     - These files are specifically formatted for LXD, a system container manager. They contain LXD metadata and when combined with :ref:`root tarballs <root_tarball>` (``-root.tar.xz``) can be used to instantiate LXD containers. You can use ``.lxd.tar.xz`` files to help create isolated environments with specific configurations and applications, ensuring consistent container deployments across LXD hosts.
+     - These files are specifically formatted for LXD, a system container manager. They contain LXD metadata and when combined with :ref:`root tarballs <root-tarball-ref>` (``-root.tar.xz``) can be used to instantiate LXD containers. You can use ``.lxd.tar.xz`` files to help create isolated environments with specific configurations and applications, ensuring consistent container deployments across LXD hosts.
 
-.. _ova:
+.. _ova-ref:
 
 Open Virtual Appliance (OVA)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -77,6 +85,8 @@ Open Virtual Appliance (OVA)
    * - Use cases
      - OVA files encapsulate an entire virtual machine setup including configuration, disk images and other metadata. They are used for easy deployment of virtual appliances across different virtualisation providers such as VirtualBox or VMware. You can import an ``.ova`` file into VirtualBox to quickly deploy a pre-configured virtual machine. See our how-to guide :ref:`run-an-ova-using-virtualbox` for more information.
 
+.. _qcow-ref:
+
 QEMU Copy On Write (QCOW)
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 .. list-table::
@@ -97,7 +107,7 @@ QEMU Copy On Write (QCOW)
 
        Refer to :ref:`qcow-qemu` for instructions on using QCOW images with QEMU.
 
-.. _root_tarball:
+.. _root-tarball-ref:
 
 Root tarball
 ~~~~~~~~~~~~
@@ -114,6 +124,8 @@ Root tarball
    * - Use cases
      - These files are used for deploying base system images in virtual machines and containers. You can use ``.root.tar.xz`` files to distribute pre-configured root file systems that can be deployed directly into virtual machines or container runtimes like Docker or Kubernetes.
 
+.. _squashfs-ref:
+
 SquashFS
 ~~~~~~~~
 .. list-table::
@@ -129,6 +141,8 @@ SquashFS
    * - Use cases
      - SquashFS files are used for embedding file systems in read-only environments, often in embedded systems or live CDs. In cloud environments, they are used for distributing lightweight operating system images that are ready to use. You can use a ``.squashfs`` file containing a minimal Linux distribution to create container images that boot quickly and require minimal storage space.
 
+.. _tarball-ref:
+
 Tarball (gzip)
 ~~~~~~~~~~~~~~
 .. list-table::
@@ -144,6 +158,8 @@ Tarball (gzip)
    * - Use cases
      - Our ``.tar.gz`` archives are used to distribute complete file system images along with the kernel for various operating systems and virtualisation platforms. They allow extraction and booting of the entire system on compatible hardware or virtual machines.
 
+.. _vagrant-box-ref:
+
 Vagrant box
 ~~~~~~~~~~~
 .. list-table::
@@ -159,6 +175,8 @@ Vagrant box
    * - Use cases
      - These files contain a virtual machine image along with metadata required for Vagrant. Vagrant simplifies the creation and provisioning of virtual environments, making it easier to manage and share development environments across different systems. You can use a ``.box`` file along with a supported provider to quickly set up environments with specific configurations, tools and dependencies. All Vagrant boxes are provider specific, with our boxes having been built for VirtualBox.
 
+.. _vhd-ref:
+
 Virtual Hard Disk (VHD)
 ~~~~~~~~~~~~~~~~~~~~~~~
 .. list-table::