The Clear Linux* OS can be automatically provisioned in bulk using a combination of the Clear Linux OS installer, Ister, and ICIS. This guide covers how to perform a bulk provision of Clear Linux OS using Ister and ICIS.

To configure a bulk provision, Ister configuration files and cloud-init files must be defined. Hosting the configuration files in ICIS allows Ister to use them during the installation. The Ister configuration files allow us to customize the installation process. The cloud-init* files allow us to customize the instance of the installation.

Figure 1 depicts the flow of information between a PXE server and a PXE client that needs to be set up to perform a bulk provision.

Bulk provision information flow

Figure 1: Bulk provision information flow

Prerequisites

Before performing a bulk provision, verify you have a PXE server capable of performing network boots of Clear Linux OS. Please refer to our guide on how to perform an iPXE boot using NAT for details.

Because a bulk provision relies on a reboot, ensure the following preparations have been made:

  • No existing disks are bootable.
  • The network boot option must come immediately after the disk boot option on any computer performing the installation.

Configuration

  1. Install ICIS by following the getting started guide on the ICIS GitHub repository.

  2. Create an Ister installation file and save it to the static/ister directory within the web hosting directory for ICIS. The installation file is a JSON block and provides Ister with the steps it needs to perform an installation. The file outlines what partitions, file systems, and mount points Ister should set up. Lastly, the file outlines which bundles to install. See our Available bundles document for the list of available bundles. The following example shows the contents of an Ister installation file:

    {
        "DestinationType":"physical",
        "PartitionLayout":[
            {"disk":"sda", "partition":1, "size":"512M", "type":"EFI"},
            {"disk":"sda", "partition":2, "size":"512M", "type":"swap"},
            {"disk":"sda", "partition":3, "size":"rest", "type":"linux"}
        ],
        "FilesystemTypes":[
            {"disk":"sda", "partition":1, "type":"vfat"},
            {"disk":"sda", "partition":2, "type":"swap"},
            {"disk":"sda", "partition":3, "type":"ext4"}
        ],
        "PartitionMountPoints":[
            {"disk":"sda", "partition":1, "mount":"/boot"},
            {"disk":"sda", "partition":3, "mount":"/"}
        ],
        "Version":"latest",
        "Bundles":[
            "kernel-native",
            "os-core",
            "os-core-update",
            "os-cloudguest"
        ],
        "IsterCloudInitSvc":"http://192.168.1.1:60000/icis/"
    }
    

    Important

    Every Ister installation file hosted on ICIS must contain the the IsterCloudInitSvc parameter as well as the os-cloudguest bundle. These entries allow Ister to customize an instance of of an install.

  3. Create an Ister configuration file to define the location of the Ister installation file. Save it to the static/ister directory within the web hosting directory of ICIS. The following example shows an Ister configuration file:

    template=http://192.168.1.1:60000/icis/static/ister/ister.json
    
  4. Modify the iPXE boot script by adding a kernel parameter to the command line for booting the network image. Add the kernel parameter isterconf with the location of the Ister configuration file hosted on ICIS as the kernel parameter value. The following example shows an iPXE boot script with the isterconf parameter:

    #!ipxe
    kernel linux quiet init=/usr/lib/systemd/systemd-bootchart initcall_debug tsc=reliable no_timer_check noreplace-smp rw initrd=initrd isterconf=http://192.168.1.1:60000/icis/static/ister/ister.conf
    initrd initrd
    boot
    

    Note

    After the network image of Clear Linux OS boots, Ister inspects the parameters used during boot in /proc/cmdline to find the location of the Ister configuration file.

  5. Write a cloud-init document to customize the instance of the installation according to your requirements. The cloud-init Read the Docs provides a guide on how to write a cloud-init document. The guide covers the customization options provided by cloud-init after an installation.

  6. Save the cloud-init document to the static/roles directory within the web hosting directory for ICIS with the name of a role you would like to create. For example, a role may be “database”, “web”, or “ciao”.

  7. After creating the roles, also known as cloud-init files, assign roles to MAC addresses of PXE clients. To do so, modify the config.txt file in the static directory within the web hosting directory of ICIS. The following example shows one such assignment:

    # MAC address,role
    00:01:02:03:04:05,ciao
    

    If MAC addresses of PXE clients are not listed within the config.txt file, a default role for those MAC address may be defined as follows:

    # MAC address,role
    default,ciao
    
  8. Verify the following URLs are accessible on your local network:

    • http://192.168.1.1:60000/icis/static/ister/ister.conf
    • http://192.168.1.1:60000/icis/static/ister/ister.json
    • http://192.168.1.1:60000/icis/get_config/<MAC address>
    • http://192.168.1.1:60000/icis/get_role/<role>
    • http://192.168.1.1:60000/ipxe/ipxe_boot_script.txt
  9. Power on the PXE client and watch it boot and install Clear Linux OS.

  10. Power-cycle the PXE client and watch it customize the Clear Linux OS installation.

Congratulations! You have successfully performed a bulk provision of Clear Linux OS.