diff --git a/doc/explanation/cloudinit-autoinstall-interaction.rst b/doc/explanation/cloudinit-autoinstall-interaction.rst new file mode 100644 index 00000000..3ea2a76f --- /dev/null +++ b/doc/explanation/cloudinit-autoinstall-interaction.rst @@ -0,0 +1,35 @@ +.. _cloudinit-autoinstall-interaction: + +Cloud-init and autoinstall interaction +====================================== + +While cloud-init may provide the autoinstall configuration to the Ubuntu +installer, it does not process the autoinstall directives itself. + +Cloud-init runs in both the ephemeral system (during installation) and in the target +system during first boot. Cloud-init then becomes inert for every subsequent +reboot. + +To modify the ephemeral system with cloud-init, any +:external+cloud-init:ref:`#cloud-config module schema keys` can +be provided. If instead cloud-init directives are intended to modify the system +being installed, they must appear under a :ref:`ai-user-data` section under +``autoinstall:``. + +.. code-block:: yaml + + #cloud-config + # cloud-init directives may optionally be specified here. + # These directives affect the ephemeral system performing the installation. + + autoinstall: + # autoinstall directives must be specified here, not directly at the + # top level. These directives are processed by the Ubuntu Installer, + # and configure the target system to be installed. + + user-data: + # cloud-init directives may also be optionally be specified here. + # These directives also affect the target system to be installed, + # and are processed on first boot. + +For an overview of the methods used to provide the autoinstall configuration to the Ubuntu installer, go to :ref:`Providing autoinstall configuration `. diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst index d4eb2265..11f9871a 100644 --- a/doc/explanation/index.rst +++ b/doc/explanation/index.rst @@ -10,6 +10,6 @@ About the Server installer .. toctree:: :maxdepth: 1 - - operate-server-installer - configure-storage + + cloudinit-autoinstall-interaction + zero-touch-autoinstall diff --git a/doc/explanation/zero-touch-autoinstall.rst b/doc/explanation/zero-touch-autoinstall.rst new file mode 100644 index 00000000..ae556193 --- /dev/null +++ b/doc/explanation/zero-touch-autoinstall.rst @@ -0,0 +1,18 @@ +Zero-touch deployment with autoinstall +====================================== + +The Ubuntu Installer contains a safeguard, intended to prevent USB Flash Drives +with an :code:`autoinstall.yaml` file from wiping out the wrong system. + +Before the Ubuntu Installer actually makes changes to the target system, a +prompt is shown. :: + + start: subiquity/Meta/status_GET + Confirmation is required to continue. + Add 'autoinstall' to your kernel command line to avoid this + + + Continue with autoinstall? (yes|no) + +To bypass this prompt, arrange for the argument :code:`autoinstall` to be +present on the kernel command line. diff --git a/doc/tutorial/basic-server-installation.rst b/doc/howto/basic-server-installation.rst similarity index 98% rename from doc/tutorial/basic-server-installation.rst rename to doc/howto/basic-server-installation.rst index e80e2dfe..30cf050a 100644 --- a/doc/tutorial/basic-server-installation.rst +++ b/doc/howto/basic-server-installation.rst @@ -1,7 +1,7 @@ Basic server installation ========================= -This chapter provides an overview of how to install Ubuntu Server Edition. See also the guide on :ref:`how to operate the installer ` for more information on using the installer, and the :doc:`screen-by-screen guide ` for more information about each of the installer screens. +This chapter provides an overview of how to install Ubuntu Server Edition. See also the guide on :ref:`how to operate the installer ` for more information on using the installer, and the :ref:`screen-by-screen guide ` for more information about each of the installer screens. Preparing to install -------------------- diff --git a/doc/explanation/configure-storage.rst b/doc/howto/configure-storage.rst similarity index 100% rename from doc/explanation/configure-storage.rst rename to doc/howto/configure-storage.rst diff --git a/doc/explanation/figures/basic-installation-start-screen.png b/doc/howto/figures/basic-installation-start-screen.png similarity index 100% rename from doc/explanation/figures/basic-installation-start-screen.png rename to doc/howto/figures/basic-installation-start-screen.png diff --git a/doc/explanation/figures/configure-storage-GPT-partition.png b/doc/howto/figures/configure-storage-GPT-partition.png similarity index 100% rename from doc/explanation/figures/configure-storage-GPT-partition.png rename to doc/howto/figures/configure-storage-GPT-partition.png diff --git a/doc/explanation/figures/configure-storage-boot-devices.png b/doc/howto/figures/configure-storage-boot-devices.png similarity index 100% rename from doc/explanation/figures/configure-storage-boot-devices.png rename to doc/howto/figures/configure-storage-boot-devices.png diff --git a/doc/explanation/figures/configure-storage-guided-options.png b/doc/howto/figures/configure-storage-guided-options.png similarity index 100% rename from doc/explanation/figures/configure-storage-guided-options.png rename to doc/howto/figures/configure-storage-guided-options.png diff --git a/doc/explanation/figures/configure-storage-lvm.png b/doc/howto/figures/configure-storage-lvm.png similarity index 100% rename from doc/explanation/figures/configure-storage-lvm.png rename to doc/howto/figures/configure-storage-lvm.png diff --git a/doc/explanation/figures/configure-storage-main-screen.png b/doc/howto/figures/configure-storage-main-screen.png similarity index 100% rename from doc/explanation/figures/configure-storage-main-screen.png rename to doc/howto/figures/configure-storage-main-screen.png diff --git a/doc/explanation/figures/configure-storage-partitions.png b/doc/howto/figures/configure-storage-partitions.png similarity index 100% rename from doc/explanation/figures/configure-storage-partitions.png rename to doc/howto/figures/configure-storage-partitions.png diff --git a/doc/explanation/figures/configure-storage-raid.png b/doc/howto/figures/configure-storage-raid.png similarity index 100% rename from doc/explanation/figures/configure-storage-raid.png rename to doc/howto/figures/configure-storage-raid.png diff --git a/doc/howto/index.rst b/doc/howto/index.rst index b987d577..0dc98869 100644 --- a/doc/howto/index.rst +++ b/doc/howto/index.rst @@ -14,14 +14,16 @@ Getting started with autoinstall .. toctree:: :maxdepth: 1 - - Autoinstall quick start - Autoinstall quick start for s390x + + autoinstall-quickstart + autoinstall-quickstart-s390x + basic-server-installation + configure-storage Found a problem? ---------------- .. toctree:: :maxdepth: 1 - + report-bugs diff --git a/doc/intro-to-autoinstall.rst b/doc/intro-to-autoinstall.rst index 1cc5a3d7..c1b699d3 100644 --- a/doc/intro-to-autoinstall.rst +++ b/doc/intro-to-autoinstall.rst @@ -1,7 +1,7 @@ .. _tutorial_intro-to-autoinstall: Introduction to autoinstall -*************************** +=========================== Automatic Ubuntu installation is performed with the autoinstall format. You might also know this feature as "unattended", "hands-off" or "preseeded" @@ -11,13 +11,18 @@ This format is supported in the following installers: * Ubuntu Server, version 20.04 and later * Ubuntu Desktop, version 23.04 and later -Automatic installation lets you answer all those configuration questions ahead of +Automatic installation lets you answer all configuration questions ahead of time with an *autoinstall configuration* and lets the installation process run without any interaction. +For more details on the relationship between autoinstall and cloud-init, as well as their respective functions, go to: + +* :ref:`Cloud-init and autoinstall interaction ` +* :ref:`Providing autoinstall configuration ` + Differences from `debian-installer` preseeding -============================================== +---------------------------------------------- *preseeds* are the way to automate an installer based on `debian-installer` (also known as d-i). @@ -34,233 +39,8 @@ Autoinstalls differ from preseeds in the following ways: those. -Providing the autoinstall configuration -======================================= - -There are 2 ways to provide the autoinstall configuration: - * Provide :external+cloud-init:ref:`#cloud-config user data ` containing ``autoinstall:`` - configuration directives to cloud-init at boot time - * Directly on the installation media - -Autoinstall by way of `cloud-config` ------------------------------------- - -The suggested way of providing autoinstall configuration to the Ubuntu installer is -via cloud-init. This allows the configuration to be applied to the installer -without having to modify the installation media. - -The autoinstall configuration is provided via cloud-init configuration, which is -almost endlessly flexible. In most scenarios the easiest way will be to provide -user data via the :external+cloud-init:ref:`datasource_nocloud` data source. - -When providing autoinstall via cloud-init, the autoinstall configuration is provided -as :external+cloud-init:ref:`user_data_formats-cloud_config`. This -means we need a :code:`#cloud-config` header. The autoinstall directives are -placed under a top level :code:`autoinstall:` key, like so: - -.. code-block:: yaml - - #cloud-config - autoinstall: - version: 1 - .... - -.. note:: - - :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain - the ``#cloud-config`` header to be recognised as a valid cloud configuration data - file. - -Autoinstall on the installation media -------------------------------------- - -Another option for supplying autoinstall to the Ubuntu installer is to place a -file named :code:`autoinstall.yaml` on the installation media itself. - -There are two potential locations that Subiquity will check for the -:code:`autoinstall.yaml` file: - -* At the root of the "CD-ROM". When you write the installation ISO to a USB - Flash Drive, this can be done by copying the :code:`autoinstall.yaml` to the - partition containing the contents of the ISO - i.e., - in the directory containing the ``casper`` sub-directory. -* On the rootfs of the installation system - this option will typically - require modifying the installation ISO and is not suggested, but is - supported. - -Alternatively, you can pass the location of the autoinstall file on the kernel -command line via the :code:`subiquity.autoinstallpath` parameter, where the -path is relative to the rootfs of the installation system. For example: - -* :code:`subiquity.autoinstallpath=path/to/autoinstall.yaml` - - -Order precedence of the autoinstall locations -============================================= - -Since there are many ways to specify the autoinstall file, it may happen that -multiple locations are specified at once. Subiquity will look for the -autoinstall file in the following order and pick the first existing one: - -1. Kernel command line -2. Root of the installation system -3. `cloud-config` -4. Root of the CD-ROM (ISO) - - -Cloud-init and autoinstall interaction -====================================== - -Cloud-init runs in both the ephemeral system (during installation) and in the target -system during first boot. Cloud-init then becomes inert for every subsequent -reboot. - -While cloud-init may provide the autoinstall configuration to the Ubuntu -installer, it does not process the autoinstall directives itself. - -To modify the ephemeral system with cloud-init, any -:external+cloud-init:ref:`#cloud-config module schema keys` can -be provided. If instead cloud-init directives are intended to modify the system -being installed, they must appear under a :ref:`ai-user-data` section under -``autoinstall:``. - -.. code-block:: yaml - - #cloud-config - # cloud-init directives may optionally be specified here. - # These directives affect the ephemeral system performing the installation. - - autoinstall: - # autoinstall directives must be specified here, not directly at the - # top level. These directives are processed by the Ubuntu Installer, - # and configure the target system to be installed. - - user-data: - # cloud-init directives may also be optionally be specified here. - # These directives also affect the target system to be installed, - # and are processed on first boot. - - -Zero-touch deployment with autoinstall -====================================== - -The Ubuntu Installer contains a safeguard, intended to prevent USB Flash Drives -with an :code:`autoinstall.yaml` file from wiping out the wrong system. - -Before the Ubuntu Installer actually makes changes to the target system, a -prompt is shown. :: - - start: subiquity/Meta/status_GET - Confirmation is required to continue. - Add 'autoinstall' to your kernel command line to avoid this - - - Continue with autoinstall? (yes|no) - -To bypass this prompt, arrange for the argument :code:`autoinstall` to be -present on the kernel command line. - - -Creating an autoinstall configuration -===================================== - -When any system is installed using the Ubuntu installer, an autoinstall file -for repeating the installation is created at -:code:`/var/log/installer/autoinstall-user-data`. - - -The structure of an autoinstall configuration -============================================= - -See the :ref:`ai` for full details on the supported autoinstall directives. - -A minimal autoinstall configuration in -:external+cloud-init:ref:`user_data_formats-cloud_config` format looks like: - -.. code-block:: yaml - - #cloud-config - autoinstall: - version: 1 - identity: - hostname: hostname - username: username - password: $crypted_pass - -Here is an example file that shows off most of the autoinstall directives: - -.. parsed-literal:: - - #cloud-config - autoinstall: - :ref:`ai-version`: 1 - :ref:`ai-reporting`: - hook: - type: webhook - endpoint: http\://example.com/endpoint/path - :ref:`ai-early-commands`: - - ping -c1 198.162.1.1 - :ref:`ai-locale`: en_US - :ref:`ai-keyboard`: - layout: gb - variant: dvorak - :ref:`ai-network`: - network: - version: 2 - ethernets: - enp0s25: - dhcp4: yes - enp3s0: {} - enp4s0: {} - bonds: - bond0: - dhcp4: yes - interfaces: - - enp3s0 - - enp4s0 - parameters: - mode: active-backup - primary: enp3s0 - :ref:`ai-proxy`: http\://squid.internal:3128/ - :ref:`ai-apt`: - primary: - - arches: [default] - uri: http\://repo.internal/ - sources: - my-ppa.list: - source: "deb http\://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main" - keyid: B59D 5F15 97A5 04B7 E230 6DCA 0620 BBCF 0368 3F77 - :ref:`ai-storage`: - layout: - name: lvm - :ref:`ai-identity`: - hostname: hostname - username: username - password: $crypted_pass - :ref:`ai-ssh`: - install-server: yes - authorized-keys: - - $key - allow-pw: no - :ref:`ai-snaps`: - - name: go - channel: 1.20/stable - classic: true - :ref:`ai-debconf-selections`: | - bind9 bind9/run-resolvconf boolean false - :ref:`ai-packages`: - - libreoffice - - dns-server^ - :ref:`ai-user-data`: - disable_root: false - :ref:`ai-late-commands`: - - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub - :ref:`ai-error-commands`: - - tar c /var/log/installer | nc 192.168.0.1 1000 - - Error handling -============== +-------------- Progress through the installer is reported via the :ref:`ai-reporting` system, including errors. In addition, when a fatal error occurs, the diff --git a/doc/tutorial/creating-autoinstall-configuration.rst b/doc/tutorial/creating-autoinstall-configuration.rst new file mode 100644 index 00000000..8dc917d4 --- /dev/null +++ b/doc/tutorial/creating-autoinstall-configuration.rst @@ -0,0 +1,91 @@ +Creating autoinstall configuration +=================================== + +When any system is installed using the Ubuntu installer, an autoinstall file for repeating the installation is created at :code:`/var/log/installer/autoinstall-user-data`. :ref:`providing-autoinstall` describes the two ways of delivering this autoinstall configuration to Ubuntu installer. + + +The structure of an autoinstall configuration +--------------------------------------------- + +Go to the :ref:`ai` for full details on the supported autoinstall directives. + +.. code-block:: yaml + + #cloud-config + autoinstall: + version: 1 + identity: + hostname: hostname + username: username + password: $crypted_pass + +Here is an example file that shows most of the autoinstall directives: + +.. parsed-literal:: + + #cloud-config + autoinstall: + :ref:`ai-version`: 1 + :ref:`ai-reporting`: + hook: + type: webhook + endpoint: http\://example.com/endpoint/path + :ref:`ai-early-commands`: + - ping -c1 198.162.1.1 + :ref:`ai-locale`: en_US + :ref:`ai-keyboard`: + layout: gb + variant: dvorak + :ref:`ai-network`: + network: + version: 2 + ethernets: + enp0s25: + dhcp4: yes + enp3s0: {} + enp4s0: {} + bonds: + bond0: + dhcp4: yes + interfaces: + - enp3s0 + - enp4s0 + parameters: + mode: active-backup + primary: enp3s0 + :ref:`ai-proxy`: http\://squid.internal:3128/ + :ref:`ai-apt`: + primary: + - arches: [default] + uri: http\://repo.internal/ + sources: + my-ppa.list: + source: "deb http\://ppa.launchpad.net/curtin-dev/test-archive/ubuntu $RELEASE main" + keyid: B59D 5F15 97A5 04B7 E230 6DCA 0620 BBCF 0368 3F77 + :ref:`ai-storage`: + layout: + name: lvm + :ref:`ai-identity`: + hostname: hostname + username: username + password: $crypted_pass + :ref:`ai-ssh`: + install-server: yes + authorized-keys: + - $key + allow-pw: no + :ref:`ai-snaps`: + - name: go + channel: 1.20/stable + classic: true + :ref:`ai-debconf-selections`: | + bind9 bind9/run-resolvconf boolean false + :ref:`ai-packages`: + - libreoffice + - dns-server^ + :ref:`ai-user-data`: + disable_root: false + :ref:`ai-late-commands`: + - sed -ie 's/GRUB_TIMEOUT=.\*/GRUB_TIMEOUT=30/' /target/etc/default/grub + :ref:`ai-error-commands`: + - tar c /var/log/installer | nc 192.168.0.1 1000 diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 473e5efb..de0d3c19 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -15,6 +15,7 @@ This tutorial introduces the core concepts of autoinstall and is recommended as .. toctree:: :maxdepth: 1 - basic-server-installation + creating-autoinstall-configuration + providing-autoinstall + operate-server-installer screen-by-screen - diff --git a/doc/explanation/operate-server-installer.rst b/doc/tutorial/operate-server-installer.rst similarity index 100% rename from doc/explanation/operate-server-installer.rst rename to doc/tutorial/operate-server-installer.rst diff --git a/doc/tutorial/providing-autoinstall.rst b/doc/tutorial/providing-autoinstall.rst new file mode 100644 index 00000000..6e4c5cfa --- /dev/null +++ b/doc/tutorial/providing-autoinstall.rst @@ -0,0 +1,79 @@ +.. _providing-autoinstall: + +Providing autoinstall configuration +=================================== + +There are two ways to provide the autoinstall configuration: + +* :external+cloud-init:ref:`#cloud-config user data ` containing ``autoinstall:`` configuration directives for cloud-init +* Directly on the installation media + +For detailed how-to guides that provide step-by-step instructions on how to use these two methods, go to: + +* :ref:`Autoinstall quick start ` +* :ref:`Autoinstall quick start for s390x ` + + +Autoinstall by way of `cloud-config` +------------------------------------ + +The suggested way of providing autoinstall configuration to the Ubuntu installer is via cloud-init. This allows the configuration to be applied to the installer without having to modify the installation media. + +The autoinstall configuration is provided via cloud-init configuration, which is almost endlessly flexible. In most scenarios the easiest way will be to provide user data via the :external+cloud-init:ref:`datasource_nocloud` data source. + +When providing autoinstall via cloud-init, the autoinstall configuration is provided as :external+cloud-init:ref:`user_data_formats-cloud_config`. This means it requires a :code:`#cloud-config` header. The autoinstall directives are placed under a top level :code:`autoinstall:` key: + +.. code-block:: yaml + + #cloud-config + autoinstall: + version: 1 + .... + +.. note:: + + :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain the ``#cloud-config`` header to be recognised as a valid cloud configuration data file. + + +Autoinstall on the installation media +------------------------------------- + +Another option for supplying autoinstall to the Ubuntu installer is to place a file named :code:`autoinstall.yaml` on the installation media itself. + +The autoinstall configuration provided in this way is passed to the Ubuntu installer directly and does not require the top-level :code:`autoinstall:` key: + +.. code-block:: yaml + + version: 1 + .... + +Starting in 24.04 (Noble), to be consistent with the cloud-config based format, a top-level :code:`autoinstall:` keyword is allowed: + +.. code-block:: yaml + + autoinstall: + version: 1 + .... + +There are two locations that Subiquity checks for the :code:`autoinstall.yaml` file: + +* At the root of the installation medium. When writing the installation ISO to a USB flash drive, copy :code:`autoinstall.yaml` to the partition containing the contents of the ISO - i.e. to the directory containing the ``casper`` sub-directory. + +* On the root file system of the installation system - this option typically requires modifying the installation ISO and is not recommended. + +Alternatively, you can pass the location of the autoinstall file on the kernel command line via the :code:`subiquity.autoinstallpath` parameter, where the path is relative to the root directory of the installation system. For example: + +.. code-block:: + + subiquity.autoinstallpath=path/to/autoinstall.yaml` + + +Order of precedence for autoinstall locations +--------------------------------------------- + +Because there are many ways to specify the autoinstall file, it may happen that multiple locations are specified at the same time. Subiquity searches for the autoinstall file in the following order and uses the first existing one: + +1. Kernel command line +2. Root of the installation system +3. `cloud-config` +4. Root of the installation medium (ISO) diff --git a/doc/tutorial/screen-by-screen.rst b/doc/tutorial/screen-by-screen.rst index 5e3743a1..72b471cd 100644 --- a/doc/tutorial/screen-by-screen.rst +++ b/doc/tutorial/screen-by-screen.rst @@ -1,5 +1,7 @@ -Screen-by-screen installer -========================== +.. _screen-by-screen: + +Screen-by-screen installer walk-through +======================================= The installer is designed to be easy to use without documentation. This guide provides more information on each of the screens of the installer to guide you through an installation.