Merge pull request #289 from mstpn/cpc3365-lxd-and-openstack-images

Add LXD and OpenStack image documentation

.custom_wordlist.txt

@@ -18,7 +18,6 @@ Anbox
 Ansible
 Anthos
 armhf
-artifacts
 ASIC
 Authorize
 aws
@@ -206,6 +205,7 @@ OpenSCAP
 OpenShift
 OpenSSH
 openssl
+OpenStack
 OVAs
 OVF
 OwnerId

aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst

@@ -153,7 +153,7 @@ The steps needed for deploying the cluster depend on whether you need to enable
 
             ==> Wait completed after 9 minutes 35 seconds
 
-            ==> Builds finished. The artifacts of successful builds are:
+            ==> Builds finished. The artefacts of successful builds are:
             --> amazon-ebs: amis were created:
             us-east-1: ami-xxxxxxxx
 
@@ -269,4 +269,4 @@ To check that the deployed nodes have Ubuntu Pro, run:
 .. _`troubleshooting options`: https://docs.aws.amazon.com/eks/latest/userguide/troubleshooting.html
 .. _`Packer`: https://www.packer.io/
 .. _`issue`: https://bugs.launchpad.net/cloud-images/+bug/2017782
-.. _`eksctl details`: https://eksctl.io/
+.. _`eksctl details`: https://eksctl.io/

aws/aws-how-to/security/use-secureboot-and-vtpm.rst

@@ -5,7 +5,7 @@ UEFI Secure Boot is a security feature specified in UEFI, which verifies the sta
 With UEFI Secure Boot enabled, after firmware self-initialisation only cryptographically verified UEFI 
 binaries are allowed to be executed. This prevents any unauthorised modification of the instance boot flow.
 
-Trusted Platform Module (TPM) is a virtual device provided by the AWS Nitro System. It securely stores artifacts 
+Trusted Platform Module (TPM) is a virtual device provided by the AWS Nitro System. It securely stores artefacts 
 (such as passwords, certificates, or encryption keys) that are used to authenticate the instance. Check the `AWS NitroTPM documentation <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/nitrotpm.html>`_ for more details.
 
 Although UEFI Secure Boot is supported by both Ubuntu images and `EC2 <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/uefi-secure-boot.html>`_,

public-images/index.rst

@@ -23,13 +23,13 @@ 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 artifacts - A reference <public-images-reference/artifacts>`
+   .. grid-item:: :doc:`Cloud image artefacts - A reference <public-images-reference/artefacts>`
 
-      **Reference guide** for the artifacts found on `cloud-images.ubuntu.com`_.
+      **Reference guide** for the artefacts found on `cloud-images.ubuntu.com`_.
 
 
 
@@ -54,8 +54,8 @@ suggestions, fixes and constructive feedback.
    :maxdepth: 1
 
    public-images-how-to/index
-   public-images-reference/artifacts
-   Vagrant - An explanation<public-images-explanation/vagrant>
+   public-images-explanation/index
+   public-images-reference/artefacts
    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,212 @@
+.. _lxd-openstack-images:
+
+LXD and OpenStack images
+========================
+
+`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`_ 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`_ 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 :doc:`cloud image artefacts <../public-images-reference/artefacts>`
+documentation.
+
+
+How do you access them?
+-----------------------
+
+Go to `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`_: 
+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. A 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 an image for creating LXD containers and virtual machines 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`_ 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 refer to the `Manage images`_
+section of their documentation.
+
+
+How do you configure them?
+--------------------------
+
+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 `LXD containers`_ documentation.
+
+
+Configuring 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 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`_
+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/
+
+
+Configuring cloud-init
+^^^^^^^^^^^^^^^^^^^^^^
+
+`Cloud-init`_ is used to initialise cloud instances on first boot.
+Refer to `How to customise LXD image metadata for cloud-init`_ for a guide on configuring cloud-init for LXD
+before initialisation. If you want to configure ``cloud-init`` once an instance has been
+created (but not booted), refer to the `LXD docs on cloud-init`_.
+
+
+Configuring after import using CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The `LXD documentation on images`_ 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`_
+that is applicable to the QCOW images Ubuntu provides. It leverages ``libguestfs`` 
+`tools`_ in order to access and modify disk images. You can use the ``guestfish`` 
+`interactive shell`_ (which exposes the full functionality of the ``guestfs`` API) or
+rely on the ``virt-*`` tools from ``libguestfs`` to perform specific tasks. For instance, use
+``virt-cat`` for displaying files, ``virt-df`` for checking free space and
+``virt-inspector`` for inspecting VM images.
+
+
+.. Links
+.. _LXD: https://canonical.com/lxd
+.. _OpenStack: https://ubuntu.com/openstack
+.. _cloud-images.ubuntu.com: https://cloud-images.ubuntu.com/
+.. _minimal cloud images: https://cloud-images.ubuntu.com/minimal/
+.. _OpenStack command-line client: https://docs.openstack.org/ocata/admin-guide/common/cli-install-openstack-command-line-clients.html
+.. _Manage images: https://docs.openstack.org/ocata/admin-guide/common/cli-manage-images.html#create-or-update-an-image-glance
+.. _LXD containers: https://documentation.ubuntu.com/server/how-to/containers/lxd-containers/
+.. _LXD image format: https://documentation.ubuntu.com/lxd/en/latest/reference/image_format/
+.. _How to customise LXD image metadata for cloud-init: https://discourse.ubuntu.com/t/how-to-customize-lxd-image-metadata-for-cloud-init/25157
+.. _Cloud-init: https://cloudinit.readthedocs.io/en/latest/index.html
+.. _LXD docs on cloud-init: https://documentation.ubuntu.com/lxd/en/latest/cloud-init/
+.. _LXD documentation on images: https://documentation.ubuntu.com/lxd/en/latest/howto/images_manage/
+.. _modifying images: https://docs.openstack.org/image-guide/modify-images.html
+.. _tools: https://libguestfs.org/
+.. _interactive shell: https://libguestfs.org/guestfish.1.html

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-how-to/launch-with-libvirt.rst

@@ -21,7 +21,7 @@ Since we are dealing with cloud images here, we'll need a cloud-init user-data f
 Find and download an image
 --------------------------
 
-Ubuntu cloud images are hosted on https://cloud-images.ubuntu.com/. Refer to :doc:`../public-images-reference/artifacts` for a description of the various image types found there.
+Ubuntu cloud images are hosted on https://cloud-images.ubuntu.com/. Refer to :doc:`../public-images-reference/artefacts` for a description of the various image types found there.
 
 QCOW images (``.img``) are suitable for use with libvirt and the QEMU driver. Once you have identified a suitable image, download it. For example, the following would download the current daily Ubuntu 24.04 (noble) image for amd64 machines: