Merge pull request #1962 from rkratky/FR-5798_autoinstall-intro
Better introduction to autoinstall
This commit is contained in:
Robert Krátký
GitHub
commit
76440813bd
|
|
@ -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<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 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 <providing-autoinstall>`.
|
||||
|
|
@ -11,5 +11,5 @@ About the Server installer
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
operate-server-installer
|
||||
configure-storage
|
||||
cloudinit-autoinstall-interaction
|
||||
zero-touch-autoinstall
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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 <operate-server-installer>` for more information on using the installer, and the :doc:`screen-by-screen guide <screen-by-screen>` 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 <operate-server-installer>` for more information on using the installer, and the :ref:`screen-by-screen guide <screen-by-screen>` for more information about each of the installer screens.
|
||||
|
||||
Preparing to install
|
||||
--------------------
|
||||
|
Before Width: | Height: | Size: 3.4 KiB After Width: | Height: | Size: 3.4 KiB |
|
Before Width: | Height: | Size: 4.3 KiB After Width: | Height: | Size: 4.3 KiB |
|
Before Width: | Height: | Size: 2.2 KiB After Width: | Height: | Size: 2.2 KiB |
|
Before Width: | Height: | Size: 2.9 KiB After Width: | Height: | Size: 2.9 KiB |
|
Before Width: | Height: | Size: 3.5 KiB After Width: | Height: | Size: 3.5 KiB |
|
Before Width: | Height: | Size: 5.7 KiB After Width: | Height: | Size: 5.7 KiB |
|
Before Width: | Height: | Size: 2.2 KiB After Width: | Height: | Size: 2.2 KiB |
|
Before Width: | Height: | Size: 3.9 KiB After Width: | Height: | Size: 3.9 KiB |
|
|
@ -15,8 +15,10 @@ Getting started with autoinstall
|
|||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Autoinstall quick start <autoinstall-quickstart>
|
||||
Autoinstall quick start for s390x <autoinstall-quickstart-s390x>
|
||||
autoinstall-quickstart
|
||||
autoinstall-quickstart-s390x
|
||||
basic-server-installation
|
||||
configure-storage
|
||||
|
||||
Found a problem?
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -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 <cloudinit-autoinstall-interaction>`
|
||||
* :ref:`Providing autoinstall configuration <providing-autoinstall>`
|
||||
|
||||
|
||||
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 <user_data_formats-cloud_config>` 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<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 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <user_data_formats-cloud_config>` 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 <autoinstall_quick_start>`
|
||||
* :ref:`Autoinstall quick start for s390x <autoinstall_quick_start_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)
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue