diff --git a/.custom_wordlist.txt b/.custom_wordlist.txt index 8e182e86..91c29adc 100644 --- a/.custom_wordlist.txt +++ b/.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 diff --git a/aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst b/aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst index 5dc06269..241dd740 100644 --- a/aws/aws-how-to/kubernetes/deploy-ubuntu-pro-cluster.rst +++ b/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/ \ No newline at end of file +.. _`eksctl details`: https://eksctl.io/ diff --git a/aws/aws-how-to/security/use-secureboot-and-vtpm.rst b/aws/aws-how-to/security/use-secureboot-and-vtpm.rst index b09d0d2f..98d526b8 100644 --- a/aws/aws-how-to/security/use-secureboot-and-vtpm.rst +++ b/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 `_ for more details. Although UEFI Secure Boot is supported by both Ubuntu images and `EC2 `_, diff --git a/public-images/index.rst b/public-images/index.rst index 6eb1e7b5..2470c49f 100644 --- a/public-images/index.rst +++ b/public-images/index.rst @@ -23,13 +23,13 @@ In this documentation .. grid:: 1 1 2 2 :padding: 0 - .. grid-item:: :doc:`Vagrant - An explanation ` + .. grid-item:: :doc:`Explanation ` - **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 ` + .. grid-item:: :doc:`Cloud image artefacts - A reference ` - **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/index + public-images-reference/artefacts public-images-how-to/contribute-to-these-docs .. _Get support: https://ubuntu.com/cloud/public-cloud diff --git a/public-images/public-images-explanation/index.rst b/public-images/public-images-explanation/index.rst new file mode 100644 index 00000000..31998aa0 --- /dev/null +++ b/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 + Vagrant diff --git a/public-images/public-images-explanation/lxd-openstack-images.rst b/public-images/public-images-explanation/lxd-openstack-images.rst new file mode 100644 index 00000000..654d2cb2 --- /dev/null +++ b/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 +``--cloudimg--``. + +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 < 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 + + +.. code :: bash + + # edit the full image properties + lxc image edit + + +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 diff --git a/public-images/public-images-explanation/vagrant.rst b/public-images/public-images-explanation/vagrant.rst index 92934830..1c0e189e 100644 --- a/public-images/public-images-explanation/vagrant.rst +++ b/public-images/public-images-explanation/vagrant.rst @@ -1,3 +1,5 @@ +.. _vagrant-explanation: + Vagrant ======= `Vagrant `_ is a multi-provider tool for building and managing virtual machines by HashiCorp. For more information, you can check out the `Vagrant documentation `_. diff --git a/public-images/public-images-how-to/launch-with-libvirt.rst b/public-images/public-images-how-to/launch-with-libvirt.rst index ff471d6b..f168cfd8 100644 --- a/public-images/public-images-how-to/launch-with-libvirt.rst +++ b/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: diff --git a/public-images/public-images-reference/artifacts.rst b/public-images/public-images-reference/artefacts.rst similarity index 96% rename from public-images/public-images-reference/artifacts.rst rename to public-images/public-images-reference/artefacts.rst index 85c83a7d..88f3db91 100644 --- a/public-images/public-images-reference/artifacts.rst +++ b/public-images/public-images-reference/artefacts.rst @@ -1,6 +1,8 @@ -Ubuntu cloud image artifacts +.. _uci-artefacts: + +Ubuntu cloud image artefacts ============================ -This document provides detailed information on various Ubuntu cloud image artifacts available on `cloud-images.ubuntu.com `_. +This document provides detailed information on various Ubuntu cloud image artefacts available on `cloud-images.ubuntu.com `_. Images ------ @@ -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:: @@ -22,7 +26,7 @@ Initial ramdisk (initrd) :header-rows: 0 * - Extension - - ``-initrd-generic`` + - ``-initrd-generic`` * - Example filename - ``unpacked/noble-server-cloudimg-amd70-initrd-generic`` * - Format description @@ -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:: @@ -37,7 +43,7 @@ Linux kernel image :header-rows: 0 * - Extension - - ``-vmlinuz-generic`` + - ``-vmlinuz-generic`` * - Example filename - ``unpacked/noble-server-cloudimg-amd64-vmlinuz-generic`` * - Format description @@ -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:: @@ -52,15 +60,15 @@ LXD tarball :header-rows: 0 * - Extension - - ``.lxd.tar.xz`` + - ``.lxd.tar.xz`` * - Example filename - ``noble-server-cloudimg-amd64-lxd.tar.xz`` * - 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.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.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 ~~~~~~~~~~~~ @@ -106,7 +116,7 @@ Root tarball :header-rows: 0 * - Extension - - ``-root.tar.xz`` + - ``-root.tar.xz`` * - Example filename - ``noble-server-cloudimg-amd64-root.tar.xz`` * - Format description @@ -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:: @@ -136,7 +150,7 @@ Tarball (gzip) :header-rows: 0 * - Extension - - ``.tar.gz`` + - ``.tar.gz`` * - Example filename - ``noble-server-cloudimg-amd64.tar.gz`` * - Format description @@ -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:: @@ -182,7 +200,7 @@ Other files This section includes information on checksums, GPG signatures, changelogs and manifest files. These files help verify the integrity and authenticity of the images, provide details on changes between versions and list all included packages. .. note:: - On Ubuntu systems, the public keys for Ubuntu cloud images are present in ``/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg``. You can use this keyring to verify GPG signatures and checksums of downloaded artifacts with a command such as ``gpg --verify --keyring /usr/share/keyrings/ubuntu-cloudimage-keyring.gpg SHA256SUMS.gpg SHA256SUMS && sha256sum -c SHA256SUMS``. + On Ubuntu systems, the public keys for Ubuntu cloud images are present in ``/usr/share/keyrings/ubuntu-cloudimage-keyring.gpg``. You can use this keyring to verify GPG signatures and checksums of downloaded artefacts with a command such as ``gpg --verify --keyring /usr/share/keyrings/ubuntu-cloudimage-keyring.gpg SHA256SUMS.gpg SHA256SUMS && sha256sum -c SHA256SUMS``. Changelogs ~~~~~~~~~~ @@ -450,7 +468,7 @@ Checksums :header-rows: 0 * - Extension - - ``SUMS`` + - ``SUMS`` * - Example filename - ``MD5SUMS``, ``SHA256SUMS`` * - Format description