Merge pull request #1708 from dbungert/docs-autoinstall-tutorial
docs: autoinstall tutorial
This commit is contained in:
commit
7476600021
|
@ -0,0 +1,2 @@
|
||||||
|
_build
|
||||||
|
.sphinx
|
17
doc/conf.py
17
doc/conf.py
|
@ -22,7 +22,7 @@ import sys
|
||||||
# -- Project information -----------------------------------------------------
|
# -- Project information -----------------------------------------------------
|
||||||
|
|
||||||
project = 'Ubuntu Install Guide'
|
project = 'Ubuntu Install Guide'
|
||||||
copyright = f'Canonical Group Ltd, {datetime.date.today().year}'
|
copyright = 'Canonical Group Ltd'
|
||||||
|
|
||||||
# -- General configuration ---------------------------------------------------
|
# -- General configuration ---------------------------------------------------
|
||||||
|
|
||||||
|
@ -34,11 +34,17 @@ needs_sphinx = '5.1.1'
|
||||||
# ones.
|
# ones.
|
||||||
|
|
||||||
extensions = [
|
extensions = [
|
||||||
'm2r2',
|
'sphinx.ext.intersphinx',
|
||||||
'sphinx_copybutton',
|
'sphinx_copybutton',
|
||||||
'sphinx_design',
|
'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.
|
# Add any paths that contain templates here, relative to this directory.
|
||||||
|
|
||||||
|
@ -47,8 +53,8 @@ templates_path = ['_templates']
|
||||||
# The suffix of source filenames.
|
# The suffix of source filenames.
|
||||||
source_suffix = '.rst'
|
source_suffix = '.rst'
|
||||||
|
|
||||||
# The master toctree document.
|
# The root toctree document.
|
||||||
master_doc = 'index'
|
root_doc = 'index'
|
||||||
|
|
||||||
# The version info for the project you're documenting, acts as replacement for
|
# The version info for the project you're documenting, acts as replacement for
|
||||||
# |version| and |release|, also used in various other places throughout the
|
# |version| and |release|, also used in various other places throughout the
|
||||||
|
@ -62,7 +68,8 @@ master_doc = 'index'
|
||||||
# This pattern also affects html_static_path and html_extra_path.
|
# This pattern also affects html_static_path and html_extra_path.
|
||||||
|
|
||||||
exclude_patterns = [
|
exclude_patterns = [
|
||||||
".sphinx/venv/*",
|
'.sphinx/venv/*',
|
||||||
|
'README.md',
|
||||||
]
|
]
|
||||||
|
|
||||||
# Sphinx-copybutton config options:
|
# Sphinx-copybutton config options:
|
||||||
|
|
|
@ -1,7 +1,7 @@
|
||||||
.. _index:
|
.. _index:
|
||||||
|
|
||||||
Subiquity documentation
|
Ubuntu Installation documentation
|
||||||
#######################
|
#################################
|
||||||
|
|
||||||
A single sentence that says what the product is, succinctly and memorably
|
A single sentence that says what the product is, succinctly and memorably
|
||||||
consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et
|
consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et
|
||||||
|
|
|
@ -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
|
|
@ -5,6 +5,15 @@ Our reference section contains support information for Subiquity.
|
||||||
This includes details on the network requirements, API definitions, support
|
This includes details on the network requirements, API definitions, support
|
||||||
matrices and so on.
|
matrices and so on.
|
||||||
|
|
||||||
|
Autoinstall reference manual
|
||||||
|
============================
|
||||||
|
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
autoinstall-reference.rst
|
||||||
|
|
||||||
-----
|
-----
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
|
|
|
@ -11,20 +11,13 @@ capable of.
|
||||||
|
|
||||||
-----
|
-----
|
||||||
|
|
||||||
Core tutorial
|
Introduction to autoinstall
|
||||||
=============
|
===========================
|
||||||
|
|
||||||
<some blurb here>
|
This tutorial introduces the core concepts of autoinstall and is recommended as
|
||||||
|
the first step.
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
Quick-start tutorial
|
intro-to-autoinstall.rst
|
||||||
====================
|
|
||||||
|
|
||||||
<some blurb here>
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 1
|
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,258 @@
|
||||||
|
.. _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"
|
||||||
|
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: 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 ways to provide the autoinstall configuration:
|
||||||
|
* Provide :external+cloud-init:ref:`#cloud-config
|
||||||
|
user-data<user_data_formats-cloud_config>` containing ``autoinstall:``
|
||||||
|
configuration directives to cloud-init at boot time
|
||||||
|
* Directly on the install media
|
||||||
|
|
||||||
|
Autoinstall by way of cloud-config
|
||||||
|
----------------------------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
#cloud-config
|
||||||
|
autoinstall:
|
||||||
|
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
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
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 "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.
|
||||||
|
|
||||||
|
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. For example:
|
||||||
|
|
||||||
|
.. code-block:: yaml
|
||||||
|
|
||||||
|
version: 1
|
||||||
|
....
|
||||||
|
|
||||||
|
|
||||||
|
Cloud-init and autoinstall interaction
|
||||||
|
======================================
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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<modules>` 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 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.
|
||||||
|
|
||||||
|
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 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`.
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
:ref:`ai-error-commands` are executed and the traceback printed to the console.
|
||||||
|
The server then just waits.
|
Loading…
Reference in New Issue