From 1271f5da4818114830062f2a2a01a577a3ef16f5 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 13:35:04 -0600 Subject: [PATCH 01/15] doc: conf tweaks --- doc/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 3d1ba86ac..263437f11 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,7 +22,7 @@ # -- Project information ----------------------------------------------------- project = 'Ubuntu Install Guide' -copyright = f'Canonical Group Ltd, {datetime.date.today().year}' +copyright = f'Canonical Group Ltd, 2020 - {datetime.date.today().year}' # -- General configuration --------------------------------------------------- @@ -47,8 +47,8 @@ # The suffix of source filenames. source_suffix = '.rst' -# The master toctree document. -master_doc = 'index' +# The root toctree document. +root_doc = 'index' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -62,7 +62,8 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = [ - ".sphinx/venv/*", + '.sphinx/venv/*', + 'README.md', ] # Sphinx-copybutton config options: From f2ce577f8570091e2294090758468cc99c6bff68 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 13:36:57 -0600 Subject: [PATCH 02/15] doc: gitignores --- doc/.gitignore | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 doc/.gitignore diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..869f7224a --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,2 @@ +_build +.sphinx From b07df2247f8524682bf1833ae7b7fbf3faf5095c Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 13:35:23 -0600 Subject: [PATCH 03/15] doc: s/Subiquity/Ubuntu Installation --- doc/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 7c42d8b27..489cbafa1 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,7 +1,7 @@ .. _index: -Subiquity documentation -####################### +Ubuntu Installation documentation +################################# A single sentence that says what the product is, succinctly and memorably consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et From 61e9e8278358110d53c7a18074224fd6d8a6f91d Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 13:36:48 -0600 Subject: [PATCH 04/15] doc: copy and rewrite intro tutorial --- doc/tutorial/index.rst | 17 +-- doc/tutorial/intro-to-autoinstall.rst | 147 ++++++++++++++++++++++++++ 2 files changed, 152 insertions(+), 12 deletions(-) create mode 100644 doc/tutorial/intro-to-autoinstall.rst diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index bd71e58fe..e7766b1e5 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -11,20 +11,13 @@ capable of. ----- -Core tutorial -============= +Introduction to Autoinstall +=========================== - +This tutorial introduces the core concepts of autoinstall and is recommended as +the first step. .. toctree:: :maxdepth: 1 -Quick-start tutorial -==================== - - - -.. toctree:: - :maxdepth: 1 - - + intro-to-autoinstall.rst diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst new file mode 100644 index 000000000..ad683bd22 --- /dev/null +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -0,0 +1,147 @@ +.. _tutorial_intro-to-autoinstall: + +Introduction to Autoinstall +*************************** + +Ubuntu installation automation is performed with the autoinstall format. +You might also know this feature as unattended or handsoff or preseeded +installation. + +This format is supported in the following installers: + * Ubuntu Server, version 20.04 and later + * Ubuntu Desktop, version 23.04 and later + +Autoinstallation lets you answer all those configuration questions ahead of +time with an *autoinstall config* and lets the installation process run without +any interaction. + + +Differences from debian-installer preseeding +============================================ + +*preseeds* are the way to automate an installer based on debian-installer +(also known as d-i). + +Autoinstalls differ from preseeds in the following ways: + * the format is different (yaml vs debconf-set-selections) + * when the answer to a question is not present in a preseed, d-i stops and + asks the user for input. Autoinstalls are not like this: by default, if + there is any autoinstall configuration at all, the installer takes the + default for any unanswered question (and fails if there is no default). + * You can designate particular sections in the configuration as "interactive", + which means the installer will still stop and ask about those. + + +Providing the autoinstall configuration +======================================= + +There are 2 methods of providing the autoinstall configuration: + * Carried as part of cloud-config + * Directly on the install media + +Autoinstall by way of cloud-config +---------------------------------- + +The suggested method of providing autoinstall to the Ubuntu installer is by way +of cloud-init. This allows the configuration to be applied to the installer +without having to modify the install media. + +When providing autoinstall via cloud-init, the autoinstall config is wrapped in +a cloud-config header and an autoinstall top-level key, like so: + +.. code-block:: yaml + + #cloud-config + autoinstall: + version: 1 + .... + +Autoinstall on the install media +-------------------------------- + +Another option for supplying autoinstall to the Ubuntu installer is to place a +file named :code:`autoinstall.yaml` on the install media itself. + +There are two potential locations for the :code:`autoinstall.yaml` file: + * At the root of the "cdrom". When writing 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 same directory + containing the :code:`casper` directory. + * On the rootfs of the installation system - this option will typically + require modifying the installation ISO and is not suggested, but is + supported. + +Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not +require a :code:`#cloud-config` header, and does not use a top level +:code:`autoinstall` key. The autoinstall directives are placed at the top +level. + +.. code-block:: yaml + + version: 1 + .... + + +Cloud-init and Autoinstall interaction +====================================== + +While cloud-init may assist in providing the autoinstall configuration to the +Ubuntu installer, cloud-init itself is not processing the autoinstall. + +If cloud-init directives are intended to modify the ephemeral system, they +must appear at the top level of the cloud-config. If instead +cloud-init directives are intended to modify the system being installed, they +must appear under a :code:`user-data` section in :code:`autoinstall`. + +.. code-block:: yaml + + #cloud-config + # cloud-init directives may optionally be specified here. + # These directives affect the ephemeral system performing the install. + + 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. + +During autoinstall, a prompt will be shown to confirm that the install really +should proceed and start making modifications to the target system. :: + + 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 config +============================== + +When any system is installed using the Ubuntu installer, an autoinstall file +for repeating the install is created at +:code:`/var/log/installer/autoinstall-user-data`. + + +Error handling +============== + +Progress through the installer is reported via the :ref:`ai-reporting` system, +including errors. In addition, when a fatal error occurs, the +:ref:`ai-error-commands` are executed and the traceback printed to the console. +The server then just waits. From 34333f536fb1689d70ac005f25c74c7bcd323bac Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 17:23:00 -0600 Subject: [PATCH 05/15] doc: add stub reference, and sample links to it --- doc/reference/autoinstall-reference.rst | 186 ++++++++++++++++++++++++ doc/reference/index.rst | 9 ++ doc/tutorial/intro-to-autoinstall.rst | 85 +++++++++++ 3 files changed, 280 insertions(+) create mode 100644 doc/reference/autoinstall-reference.rst diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst new file mode 100644 index 000000000..624015757 --- /dev/null +++ b/doc/reference/autoinstall-reference.rst @@ -0,0 +1,186 @@ +.. _ai: + +Autoinstall Configuration Reference Manual +****************************************** + +.. _ai-active-directory: + +active-directory +================ + +stub + +.. _ai-apt: + +apt +======= + +stub + +.. _ai-codecs: + +codecs +====== + +stub + +.. _ai-debconf-selections: + +debconf-selections +================== + +stub + +.. _ai-early-commands: + +early-commands +============== + +stub + +.. _ai-error-commands: + +error-commands +============== + +stub + +.. _ai-identity: + +identity +======== + +stub + +.. _ai-interactive-sections: + +interactive-sections +==================== + +stub + +.. _ai-kernel: + +kernel +====== + +stub + +.. _ai-keyboard: + +keyboard +======== + +stub + +.. _ai-late-commands: + +late-commands +============= + +stub + +.. _ai-locale: + +locale +====== + +stub + +.. _ai-network: + +network +======= + +stub + +.. _ai-oem: + +oem +=== + +stub + +.. _ai-packages: + +packages +======== + +stub + +.. _ai-proxy: + +proxy +===== + +stub + +.. _ai-refresh-installer: + +refresh-installer +================= + +stub + +.. _ai-reporting: + +reporting +========= + +stub + +.. _ai-shutdown: + +shutdown +======== + +stub + +.. _ai-snaps: + +snaps +===== + +stub + +.. _ai-ssh: + +ssh +=== + +stub + +.. _ai-storage: + +storage +======= + +stub + +.. _ai-ubuntu-pro: + +ubuntu-pro +========== + +stub + +.. _ai-updates: + +updates +======= + +stub + +.. _ai-user-data: + +user-data +========= + +stub + +.. _ai-version: + +version +======= + +stub diff --git a/doc/reference/index.rst b/doc/reference/index.rst index 66cd7560f..d3a16c617 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -5,6 +5,15 @@ Our reference section contains support information for Subiquity. This includes details on the network requirements, API definitions, support matrices and so on. +Autoinstall Reference Manual +============================ + + +.. toctree:: + :maxdepth: 1 + + autoinstall-reference.rst + ----- .. toctree:: diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index ad683bd22..f037547db 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -138,6 +138,91 @@ for repeating the install 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 is: + +.. code-block:: yaml + + version: 1 + identity: + hostname: hostname + username: username + password: $crypted_pass + +Here is an example file that shows off most features: + +.. parsed-literal:: + + :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 ============== From 02efd6ae7ddb648221b421dad1e6f1ac1415a41c Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 6 Jul 2023 16:40:35 -0600 Subject: [PATCH 06/15] doc: intersphinx to cloud-init --- doc/conf.py | 7 +++++++ doc/tutorial/intro-to-autoinstall.rst | 10 ++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 263437f11..bdd83ec58 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -35,10 +35,17 @@ extensions = [ 'm2r2', + 'sphinx.ext.intersphinx', 'sphinx_copybutton', 'sphinx_design', ] +intersphinx_mapping = { + 'cloud-init': ( + 'https://canonical-cloud-init.readthedocs-hosted.com/en/latest', + None + ) +} # Add any paths that contain templates here, relative to this directory. diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index f037547db..4c93ada03 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -46,8 +46,14 @@ The suggested method of providing autoinstall to the Ubuntu installer is by way of cloud-init. This allows the configuration to be applied to the installer without having to modify the install media. -When providing autoinstall via cloud-init, the autoinstall config is wrapped in -a cloud-config header and an autoinstall top-level key, like so: +The autoinstall config 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 config 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 From 337c4f8cc852886636ca7ff02a8b0ab886cd93d8 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 08:58:27 -0600 Subject: [PATCH 07/15] doc: most yaml samples in ccd format --- doc/tutorial/intro-to-autoinstall.rst | 145 +++++++++++++------------- 1 file changed, 75 insertions(+), 70 deletions(-) diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index 4c93ada03..1398a717d 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -149,84 +149,89 @@ The structure of an autoinstall configuration See the :ref:`ai` for full details on the supported autoinstall directives. -A minimal autoinstall configuration is: +A minimal autoinstall configuration in +:external+cloud-init:ref:`user_data_formats-cloud_config` format looks like: .. code-block:: yaml - version: 1 - identity: - hostname: hostname - username: username - password: $crypted_pass + #cloud-config + autoinstall: + version: 1 + identity: + hostname: hostname + username: username + password: $crypted_pass Here is an example file that shows off most features: .. parsed-literal:: - :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 + #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 From 70e9b00c1416883fbf4b8d9b2fde7254a0e04c07 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 09:55:58 -0600 Subject: [PATCH 08/15] doc: fix title Co-authored-by: Sally --- doc/reference/autoinstall-reference.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/autoinstall-reference.rst b/doc/reference/autoinstall-reference.rst index 624015757..d6ac70cdc 100644 --- a/doc/reference/autoinstall-reference.rst +++ b/doc/reference/autoinstall-reference.rst @@ -1,6 +1,6 @@ .. _ai: -Autoinstall Configuration Reference Manual +Autoinstall configuration reference manual ****************************************** .. _ai-active-directory: From 35bbd4db180371606bbc4b8cb2b95ac4a67da29c Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 09:56:06 -0600 Subject: [PATCH 09/15] doc: fix index titles Co-authored-by: Sally --- doc/reference/index.rst | 2 +- doc/tutorial/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/reference/index.rst b/doc/reference/index.rst index d3a16c617..ab5afb944 100644 --- a/doc/reference/index.rst +++ b/doc/reference/index.rst @@ -5,7 +5,7 @@ Our reference section contains support information for Subiquity. This includes details on the network requirements, API definitions, support matrices and so on. -Autoinstall Reference Manual +Autoinstall reference manual ============================ diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index e7766b1e5..faefeab35 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -11,7 +11,7 @@ capable of. ----- -Introduction to Autoinstall +Introduction to autoinstall =========================== This tutorial introduces the core concepts of autoinstall and is recommended as From 1418af004f7c5be7e1d12581a4f149cf7774a44b Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 09:56:22 -0600 Subject: [PATCH 10/15] doc: many tutorial editorial improvements Co-authored-by: Sally --- doc/tutorial/intro-to-autoinstall.rst | 53 +++++++++++++++------------ 1 file changed, 30 insertions(+), 23 deletions(-) diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index 1398a717d..7da66d771 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -1,10 +1,10 @@ .. _tutorial_intro-to-autoinstall: -Introduction to Autoinstall +Introduction to autoinstall *************************** -Ubuntu installation automation is performed with the autoinstall format. -You might also know this feature as unattended or handsoff or preseeded +Automatic Ubuntu installation is performed with the autoinstall format. +You might also know this feature as "unattended", "hands-off" or "preseeded" installation. This format is supported in the following installers: @@ -23,35 +23,36 @@ Differences from debian-installer preseeding (also known as d-i). Autoinstalls differ from preseeds in the following ways: - * the format is different (yaml vs debconf-set-selections) - * when the answer to a question is not present in a preseed, d-i stops and - asks the user for input. Autoinstalls are not like this: by default, if - there is any autoinstall configuration at all, the installer takes the - default for any unanswered question (and fails if there is no default). - * You can designate particular sections in the configuration as "interactive", - which means the installer will still stop and ask about those. + * The format is different: autoinstalls use YAML instead of the preseed + debconf-set-selections + * When the answer to a question is not present in a preseed, d-i stops and + asks the user for input. By comparison, if there is any autoinstall + configuration at all, the autoinstall takes the default for any + unanswered question (and fails if there is no default). + * You can designate particular sections in the autoinstall configuration as + "interactive", which means the installer will still stop and ask about those. Providing the autoinstall configuration ======================================= -There are 2 methods of providing the autoinstall configuration: +There are 2 ways to provide the autoinstall configuration: * Carried as part of cloud-config * Directly on the install media Autoinstall by way of cloud-config ---------------------------------- -The suggested method of providing autoinstall to the Ubuntu installer is by way -of cloud-init. This allows the configuration to be applied to the installer +The suggested way of providing autoinstall config to the Ubuntu installer is +via cloud-init. This allows the configuration to be applied to the installer without having to modify the install media. The autoinstall config 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. +user data via the :external+cloud-init:ref:`datasource_nocloud` data source. When providing autoinstall via cloud-init, the autoinstall config is provided -as :external+cloud-init:ref:`user_data_formats-cloud_config`. This +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: @@ -62,6 +63,12 @@ placed under a top level :code:`autoinstall` key, like so: version: 1 .... +.. note:: + + :external+cloud-init:ref:`user_data_formats-cloud_config` files must contain + the ``#cloud-config`` header to be recognized as a valid cloud config data + file. + Autoinstall on the install media -------------------------------- @@ -69,17 +76,17 @@ Another option for supplying autoinstall to the Ubuntu installer is to place a file named :code:`autoinstall.yaml` on the install media itself. There are two potential locations for the :code:`autoinstall.yaml` file: - * At the root of the "cdrom". When writing the installation ISO to a USB + * At the root of the "cdrom". 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 same directory - containing the :code:`casper` directory. + 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. Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not require a :code:`#cloud-config` header, and does not use a top level -:code:`autoinstall` key. The autoinstall directives are placed at the top +:code:`autoinstall` key. The autoinstall directives are placed at the top level. .. code-block:: yaml @@ -88,14 +95,14 @@ level. .... -Cloud-init and Autoinstall interaction +Cloud-init and autoinstall interaction ====================================== -While cloud-init may assist in providing the autoinstall configuration to the -Ubuntu installer, cloud-init itself is not processing the autoinstall. +While cloud-init may provide the autoinstall configuration to the +Ubuntu installer, it does not process the autoinstall itself. If cloud-init directives are intended to modify the ephemeral system, they -must appear at the top level of the cloud-config. If instead +must appear at the top level of the cloud-config. If instead cloud-init directives are intended to modify the system being installed, they must appear under a :code:`user-data` section in :code:`autoinstall`. From 3f5a62af79a52c450ecdfcd6850238615d2061e8 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 10:10:10 -0600 Subject: [PATCH 11/15] doc: drop the extension to use markdown Co-authored-by: Sally --- doc/conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index bdd83ec58..164ac7dba 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -34,7 +34,6 @@ # ones. extensions = [ - 'm2r2', 'sphinx.ext.intersphinx', 'sphinx_copybutton', 'sphinx_design', From 482a2bfbd09239975375f7b4cb7ce4cda80b2318 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 12:17:10 -0600 Subject: [PATCH 12/15] doc: simpler copyright declaration --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 164ac7dba..67a2cabd5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -22,7 +22,7 @@ # -- Project information ----------------------------------------------------- project = 'Ubuntu Install Guide' -copyright = f'Canonical Group Ltd, 2020 - {datetime.date.today().year}' +copyright = 'Canonical Group Ltd' # -- General configuration --------------------------------------------------- From bc510872a40a8cfb693d66a86c7d27c91ede7f10 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 13:51:46 -0600 Subject: [PATCH 13/15] doc: further editorial improvements to tutorial Co-authored-by: Chad Smith --- doc/tutorial/intro-to-autoinstall.rst | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index 7da66d771..e604c77e1 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -37,7 +37,7 @@ Providing the autoinstall configuration ======================================= There are 2 ways to provide the autoinstall configuration: - * Carried as part of cloud-config + * Provide :external+cloud-init:ref:`#cloud-config user-data` containing `autoinstall:` configuration directives to cloud-init at boot time * Directly on the install media Autoinstall by way of cloud-config @@ -54,7 +54,7 @@ user data via the :external+cloud-init:ref:`datasource_nocloud` data source. When providing autoinstall via cloud-init, the autoinstall config 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: +placed under a top level :code:`autoinstall:` key, like so: .. code-block:: yaml @@ -98,13 +98,18 @@ level. Cloud-init and autoinstall interaction ====================================== -While cloud-init may provide the autoinstall configuration to the -Ubuntu installer, it does not process the autoinstall itself. +Cloud-init runs in both the ephemeral system, during install, and in the target +system during first boot. Cloud-init then becomes inert for every subsequent +reboot. -If cloud-init directives are intended to modify the ephemeral system, they -must appear at the top level of the cloud-config. If instead -cloud-init directives are intended to modify the system being installed, they -must appear under a :code:`user-data` section in :code:`autoinstall`. +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 From 8a3392e01a2efaef45efef8ecd2783d9d2300984 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Fri, 7 Jul 2023 14:16:31 -0600 Subject: [PATCH 14/15] doc: wording and space tweaks to tutorial --- doc/tutorial/intro-to-autoinstall.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index e604c77e1..0ba01f9f7 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -30,14 +30,17 @@ Autoinstalls differ from preseeds in the following ways: configuration at all, the autoinstall takes the default for any unanswered question (and fails if there is no default). * You can designate particular sections in the autoinstall configuration as - "interactive", which means the installer will still stop and ask about those. + "interactive", which means the installer will still stop and ask about + 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 + * Provide :external+cloud-init:ref:`#cloud-config + user-data` containing ``autoinstall:`` + configuration directives to cloud-init at boot time * Directly on the install media Autoinstall by way of cloud-config @@ -86,7 +89,7 @@ There are two potential locations for the :code:`autoinstall.yaml` file: Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not require a :code:`#cloud-config` header, and does not use a top level -:code:`autoinstall` key. The autoinstall directives are placed at the top +``autoinstall:`` key. The autoinstall directives are placed at the top level. .. code-block:: yaml @@ -134,8 +137,8 @@ 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. -During autoinstall, a prompt will be shown to confirm that the install really -should proceed and start making modifications to the target 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. @@ -174,7 +177,7 @@ A minimal autoinstall configuration in username: username password: $crypted_pass -Here is an example file that shows off most features: +Here is an example file that shows off most of the autoinstall directives: .. parsed-literal:: From 0c429010a5369bef201b1ba7da87c2ae2e48cc83 Mon Sep 17 00:00:00 2001 From: Dan Bungert Date: Thu, 13 Jul 2023 16:02:21 -0600 Subject: [PATCH 15/15] doc: editorial improvements to autoinstall tutorial Co-authored-by: Sally --- doc/tutorial/intro-to-autoinstall.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/tutorial/intro-to-autoinstall.rst b/doc/tutorial/intro-to-autoinstall.rst index 0ba01f9f7..79f5881e0 100644 --- a/doc/tutorial/intro-to-autoinstall.rst +++ b/doc/tutorial/intro-to-autoinstall.rst @@ -24,7 +24,7 @@ Differences from debian-installer preseeding Autoinstalls differ from preseeds in the following ways: * The format is different: autoinstalls use YAML instead of the preseed - debconf-set-selections + debconf-set-selections. * When the answer to a question is not present in a preseed, d-i stops and asks the user for input. By comparison, if there is any autoinstall configuration at all, the autoinstall takes the default for any @@ -79,7 +79,7 @@ Another option for supplying autoinstall to the Ubuntu installer is to place a file named :code:`autoinstall.yaml` on the install media itself. There are two potential locations for the :code:`autoinstall.yaml` file: - * At the root of the "cdrom". When you write the installation ISO to a USB + * 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. @@ -90,7 +90,7 @@ There are two potential locations for the :code:`autoinstall.yaml` file: Directly specifying autoinstall as a :code:`autoinstall.yaml` file does not require a :code:`#cloud-config` header, and does not use a top level ``autoinstall:`` key. The autoinstall directives are placed at the top -level. +level. For example: .. code-block:: yaml @@ -101,7 +101,7 @@ level. Cloud-init and autoinstall interaction ====================================== -Cloud-init runs in both the ephemeral system, during install, and in the target +Cloud-init runs in both the ephemeral system (during install) and in the target system during first boot. Cloud-init then becomes inert for every subsequent reboot.