Merge pull request #1708 from dbungert/docs-autoinstall-tutorial
docs: autoinstall tutorial
This commit is contained in:
Dan Bungert
GitHub
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 = 'Ubuntu Install Guide'
|
||||
copyright = f'Canonical Group Ltd, {datetime.date.today().year}'
|
||||
copyright = 'Canonical Group Ltd'
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
|
|
@ -34,11 +34,17 @@ needs_sphinx = '5.1.1'
|
|||
# ones.
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -47,8 +53,8 @@ templates_path = ['_templates']
|
|||
# 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 +68,8 @@ master_doc = 'index'
|
|||
# This pattern also affects html_static_path and html_extra_path.
|
||||
|
||||
exclude_patterns = [
|
||||
".sphinx/venv/*",
|
||||
'.sphinx/venv/*',
|
||||
'README.md',
|
||||
]
|
||||
|
||||
# Sphinx-copybutton config options:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
matrices and so on.
|
||||
|
||||
Autoinstall reference manual
|
||||
============================
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
autoinstall-reference.rst
|
||||
|
||||
-----
|
||||
|
||||
.. 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::
|
||||
:maxdepth: 1
|
||||
|
||||
Quick-start tutorial
|
||||
====================
|
||||
|
||||
<some blurb here>
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
|
||||
intro-to-autoinstall.rst
|
||||
|
|
|
|||
|
|
@ -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