mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-25 01:06:37 +00:00
Using the same numbering scheme as other documents
This commit is contained in:
George T Kramer
Binary file not shown.
|
After Width: | Height: | Size: 36 KiB |
Binary file not shown.
Binary file not shown.
|
Before Width: | Height: | Size: 62 KiB |
Binary file not shown.
+91
-100
@@ -29,134 +29,125 @@ One nice attribute of this system is that once the iPXE bits are created, many
|
||||
installer behaviors can be configured without having to regenerate the iPXE
|
||||
bits.
|
||||
|
||||
System Architecture
|
||||
===================
|
||||
Prerequisites
|
||||
=============
|
||||
|
||||
Stand up an iPXE server as described in the :ref:`network_boot`
|
||||
docs. Note that you will be generating your own artifacts to be served by
|
||||
PXE in a later step.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
The following diagram illustrates the flow of information between the pxe
|
||||
server and a host booting into the installer via pxe. This diagram is intended
|
||||
to show the logical flow of information, and is not a literal depiction of the
|
||||
protocol-level exchanges.
|
||||
|
||||
.. image:: _static/images/bulk-provision.png
|
||||
.. image:: _static/images/bulk-provision-flow.png
|
||||
:align: center
|
||||
:alt: pxe-icis-install-workflow
|
||||
|
||||
Application server, web server, dhcp server, tftp server are hosted on a
|
||||
single machine, but can be hosted anywhere visible to PXE clients.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
#. Land `Ister Cloud Init Service <https://github.com/clearlinux/ister-cloud-
|
||||
init- svc>`_ on the pxe server. The README in the ICIS github repo has
|
||||
directions on how to install and configure.
|
||||
|
||||
Step 1
|
||||
------
|
||||
#. Generate the installer that will load and boot over PXE. Copy the relevant
|
||||
files into the appropriate location on the iPXE server.
|
||||
|
||||
First, stand up an iPXE server as described in the :ref:`network_boot` docs.
|
||||
Note that you will be generating your own artifacts to be served by PXE in a
|
||||
later step.
|
||||
A pxe installer is generated for every release of Clear Linux OS. It can be
|
||||
found alongside the published images in
|
||||
https://download.clearlinux.org/releases/XXXXX/clear/clear-XXXXX-pxe.tar.xz
|
||||
|
||||
Alternatively, use the `create_pxe.sh
|
||||
<https://github.com/bryteise/ister/blob/master/create_pxe.sh>`_ script to
|
||||
roll your own. Note this creates the pxe-installer from the "provisioning"
|
||||
installer in Clear Linux. This is a touchless installer that takes all
|
||||
installation information from a config file. You can get this image from a
|
||||
given Clear Linux release by looking in
|
||||
https://download.clearlinux.org/releases/XXXX/clear/ where XXXX is a Clear
|
||||
Linux release number. Just download the image alongside the
|
||||
``create_pxe.sh`` script and name it ``provision.img``.
|
||||
|
||||
#. Stage config files for ``ister`` that will govern Ister's behavior. This
|
||||
includes modifying the script for ipxe boot, getting it to pass an
|
||||
additional parameter to the kernel.
|
||||
|
||||
Step 2
|
||||
------
|
||||
The magic that ties all of this together is that the pxe script conveys to
|
||||
ister the location of its configuration files via the kernel command line
|
||||
of the installer it kicks off. The kernel preserves its command line
|
||||
precisely, and ister inspects it via ``/proc/cmdline``.
|
||||
|
||||
Land `Ister Cloud Init Service <https://github.com/clearlinux/ister-cloud-init-
|
||||
svc>`_ on the pxe server. The README in the ICIS github repo has directions on
|
||||
how to install and configure.
|
||||
Here is an example pxe script:
|
||||
|
||||
Step 3
|
||||
------
|
||||
.. code-block:: console
|
||||
|
||||
Generate the installer that will load and boot over PXE. Copy the relevant files into the
|
||||
appropriate location on the iPXE server.
|
||||
#!ipxe
|
||||
kernel linux quiet rdinit=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable
|
||||
no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1/icis/static/ister/ister.conf
|
||||
initrd initrd
|
||||
boot
|
||||
|
||||
A pxe installer is generated for every release of Clear Linux OS. It can be found alongside the
|
||||
published images in https://download.clearlinux.org/releases/XXXXX/clear/clear-XXXXX-pxe.tar.xz
|
||||
When the pxe installer kicks off ``ister``, it will make note of the
|
||||
location of the ``conf`` file that was given on the kernel command line, and
|
||||
fetch the file. This file then tells ``ister`` where to get the json
|
||||
template file that describes partition schemes, and which version of Clear
|
||||
Linux to install. This means that so long as the contents of a release are
|
||||
compatible with the version of software update (``swupd``) in the installer,
|
||||
this pxe installer can be told to install a newer version of Clear Linux
|
||||
simply by tweaking the json on the web server, rather than rolling an
|
||||
entirely new installer.
|
||||
|
||||
Alternatively, use the `create_pxe.sh <https://github.com/bryteise/ister/blob/master/create_pxe.sh>`_
|
||||
script to roll your own. Note this creates the pxe-installer from the "provisioning" installer in
|
||||
Clear Linux. This is a touchless installer that takes all installation information from a config
|
||||
file. You can get this image from a given Clear Linux release by looking
|
||||
in https://download.clearlinux.org/releases/XXXX/clear/ where XXXX is a Clear Linux release number.
|
||||
Just download the image alongside the ``create_pxe.sh`` script and name it ``provision.img``.
|
||||
One other important piece of configuration data in the json configuration
|
||||
file is the location of an ICIS configuration service. Ister will query
|
||||
ICIS for a role using the MAC address of the network interface being used
|
||||
to communicate with the ICIS service. Ister will then fetch that specific
|
||||
:file:`cloud-init` file and ``configure ucd`` to run on first-boot against
|
||||
that config file.
|
||||
|
||||
Step 4
|
||||
------
|
||||
The `Ister Cloud Init Service <https://github.com/clearlinux/ister-cloud-init-svc>`_ github repo
|
||||
has example ister configuration files under ``static/ister``.
|
||||
|
||||
Stage config files for ``ister`` that will govern Ister's behavior. This includes modifying the
|
||||
script for ipxe boot, getting it to pass an additional parameter to the kernel.
|
||||
Here is an example ister-template.json file.
|
||||
|
||||
The magic that ties all of this together is that the pxe script conveys to ister the location of its configuration files via the kernel command line of the installer it kicks off. The kernel preserves its command line precisely, and ister inspects it via ``/proc/cmdline``.
|
||||
.. code-block:: console
|
||||
|
||||
Here is an example pxe script:
|
||||
{
|
||||
"DestinationType" : "phyiscal",
|
||||
"PartitionLayout" : [ { "disk" : "/dev/sda", "partition" : 1,
|
||||
"size" : "64M", "type" : "EFI" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2,
|
||||
"size" : "2G", "type" : "linux" } ],
|
||||
"FilesystemTypes" : [ { "disk" : "/dev/sda", "partition" : 1, "type" : "vfat" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2, "type" : "ext4" } ],
|
||||
"PartitionMountPoints" : [ { "disk" : "/dev/sda", "partition" : 1,
|
||||
"mount" : "/boot" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2,
|
||||
"mount" : "/" } ],
|
||||
"Version": 6580,
|
||||
"Bundles": ["kernel-native", "os-core-update", "os-core",
|
||||
"bootloader", "sysadmin-hostmgmt", "openssh-server"],
|
||||
"PostNonChroot": ["./installation-image-post-update-version.py"],
|
||||
"IsterCloudInitSvc": ["http://192.168.1.1/icis/"]
|
||||
}
|
||||
|
||||
.. code-block:: console
|
||||
#. Configure ICIS to map MAC addresses to role files appropriately. Then create the role files, which
|
||||
are ``cloud-init`` configuration files. Note, it is possible to simply specify a "default" role for
|
||||
any unmatched MAC address; this may be handy when all install targets are to be configured identically.
|
||||
|
||||
#!ipxe
|
||||
kernel linux quiet rdinit=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable
|
||||
no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1/icis/static/ister/ister.conf
|
||||
initrd initrd
|
||||
boot
|
||||
#. Final pre-flight check. Assuming your iPXE server is at 192.168.1.1, all of the
|
||||
following urls need to be working:
|
||||
|
||||
When the pxe installer kicks off ``ister``, it will make note of the location of the ``conf`` file
|
||||
that was given on the kernel command line, and fetch the file. This file then tells ``ister`` where
|
||||
to get the json template file that describes partition schemes, and which version of Clear Linux to
|
||||
install. This means that so long as the contents of a release are compatible with the version of
|
||||
software update (``swupd``) in the installer, this pxe installer can be told to install a newer
|
||||
version of Clear Linux simply by tweaking the json on the web server, rather than rolling an
|
||||
entirely new installer.
|
||||
* http://192.168.1.1/icis/static/ister/ister.conf
|
||||
* http://192.168.1.1/icis/static/ister/ister_config.json
|
||||
* http://192.168.1.1/icis/get_config/<MAC ADDR>
|
||||
* http://192.168.1.1/icis/get_role/<role returned from previous url>
|
||||
* http://192.168.1.1/ipxe_boot_script.txt
|
||||
|
||||
One other important piece of configuration data in the json configuration file is the location of
|
||||
an ICIS configuration service. Ister will query ICIS for a role using the MAC address of the network
|
||||
interface being used to communicate with the ICIS service. Ister will then fetch that specific
|
||||
:file:`cloud-init` file and ``configure ucd`` to run on first-boot against that config file.
|
||||
|
||||
The `Ister Cloud Init Service <https://github.com/clearlinux/ister-cloud-init-svc>`_ github repo
|
||||
has example ister configuration files under ``static/ister``.
|
||||
|
||||
Here is an example ister-template.json file.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
{
|
||||
"DestinationType" : "phyiscal",
|
||||
"PartitionLayout" : [ { "disk" : "/dev/sda", "partition" : 1,
|
||||
"size" : "64M", "type" : "EFI" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2,
|
||||
"size" : "2G", "type" : "linux" } ],
|
||||
"FilesystemTypes" : [ { "disk" : "/dev/sda", "partition" : 1, "type" : "vfat" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2, "type" : "ext4" } ],
|
||||
"PartitionMountPoints" : [ { "disk" : "/dev/sda", "partition" : 1,
|
||||
"mount" : "/boot" },
|
||||
{ "disk" : "/dev/sda", "partition" : 2,
|
||||
"mount" : "/" } ],
|
||||
"Version": 6580,
|
||||
"Bundles": ["kernel-native", "os-core-update", "os-core",
|
||||
"bootloader", "sysadmin-hostmgmt", "openssh-server"],
|
||||
"PostNonChroot": ["./installation-image-post-update-version.py"],
|
||||
"IsterCloudInitSvc": ["http://192.168.1.1/icis/"]
|
||||
}
|
||||
|
||||
Step 5
|
||||
------
|
||||
|
||||
Configure ICIS to map MAC addresses to role files appropriately. Then create the role files, which
|
||||
are ``cloud-init`` configuration files. Note, it is possible to simply specify a "default" role for
|
||||
any unmatched MAC address; this may be handy when all install targets are to be configured identically.
|
||||
|
||||
Step 6
|
||||
------
|
||||
|
||||
Final pre-flight check. Assuming your iPXE server is at 192.168.1.1, all of the
|
||||
following urls need to be working:
|
||||
|
||||
* http://192.168.1.1/icis/static/ister/ister.conf
|
||||
* http://192.168.1.1/icis/static/ister/ister_config.json
|
||||
* http://192.168.1.1/icis/get_config/<MAC ADDR>
|
||||
* http://192.168.1.1/icis/get_role/<role returned from previous url>
|
||||
* http://192.168.1.1/ipxe_boot_script.txt
|
||||
|
||||
Step 7
|
||||
------
|
||||
|
||||
Boot an iPXE client and watch Clear Linux install.
|
||||
#. Boot an iPXE client and watch Clear Linux install.
|
||||
|
||||
|
||||
.. _icis: https://github.com/clearlinux/ister-cloud-init-svc
|
||||
|
||||
Reference in New Issue
Block a user