Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / The Adaptable Linux Platform Guide / Deployment

2 Deployment

2.1 Introduction

The Adaptable Linux Platform (ALP) is distributed as a pre-built raw disk image. You can download the latest published image from https://download.opensuse.org/repositories/SUSE:/ALP:/PUBLISH/images/. There are two types of ALP images, depending whether you intend to run ALP on an encrypted disk or an unencrypted disk. You can deploy ALP either with a minimal initial configuration (JeOS Firstboot), or use additional tools—Combustion and Ignition—to specify a detailed system setup.

2.2 First boot detection

The deployment configuration runs on the first boot only. To distinguish between the first and subsequent boots, the flag file /boot/writable/firstboot_happened is created after the first boot finishes. If the file is not present in the file system, the attribute ignition.firstboot is passed to the kernel command line, which triggers the creation of initramfs (Ignition) or running a specific dracut module (Combustion). After completing the first boot, the /boot/writable/firstboot_happened flag file is created.

Note
Note: The flag file is always created

Even though the configuration may not be successful, due to improper or missing configuration files, the /boot/writable/firstboot_happened flag file is created.

Tip
Tip

You may force the first boot configuration on subsequent boot by passing the ignition.firstboot attribute to the kernel command line or by deleting the /boot/writable/firstboot_happened flag file.

2.3 Default partitioning

The pre-built images are delivered with a default partitioning scheme. You can change it during the first boot by using Ignition or Combustion.

Important
Important: BTRFS is mandatory for the root file system

If you intend to perform any changes to the default partitioning scheme, the root file system must be BTRFS.

Each image has the following subvolumes:

 /home
 /root
 /opt
 /srv
 /usr/local
 /var

The /etc directory is mounted as overlayfs, where the upper directory is mounted to /var/lib/overlay/1/etc/.

You can recognize the subvolumes mounted by default by the option x-initrd.mount in /etc/fstab. Other subvolumes or partitions must be configured either by Ignition or Combustion.

Deploying ALP

2.5.1 Introduction

This article describes how to deploy the Adaptable Linux Platform (ALP) raw disk image. It applies to ALP running both on encrypted and unencrypted disk.

2.5.2 Hardware requirements

The minimum supported hardware requirements for deploying ALP follow:

CPU

AMD64/Intel 64 CPU architecture is supported

Maximum number of CPUs

The maximum number of CPUs supported by software design is 8192.

Memory

ALP requires at least 1 GB RAM. Bear in mind that this is a minimal value for the operation system, the actual memory size depends on the workload.

Hard disk

The minimum hard disk space is 12GB, while the recommended value is 20GB of hard disk space. Adjust the value according to the workloads of your containers.

Important
Important: Encrypted image does not expand to the full disk capacity

As of now, the encrypted image does not expand to the full disk capacity automatically. As a workaround, the following steps are required:

  1. Use the qemu-img command to increase the disk image to the desired size.

  2. Setup the virtual machine and boot it. When the JeOS Firstboot wizard asks you which method to use for encryption, select passphrase.

  3. When the system is ready, use the parted command to resize the partition where the LUKS device resides (for example, partition number 3) to the desired size.

  4. Run the cryptsetup resize luks command. When asked, enter the passphrase to resize the encrypted device.

  5. Run the transactional-update shell command to open a read-write shell in the current disk snapshot. Then resize the BTRFS file system to the desired size, for example:

    # btrfs fi resize max /
  6. Leave the shell with exit and reboot the system with reboot.

2.5.3 Deploying ALP on a KVM VM Host Server

This procedure describes steps to deploy ALP as a KVM virtual machine using the Virtual Machine Manager.

  1. Download ALP virtual machine image on the host where you will run ALP. Go to https://download.opensuse.org/repositories/SUSE:/ALP:/PUBLISH/images/ and download the latest disk image of ALP.

    For example, for the unencrypted image:

    > curl -LO https://download.opensuse.org/repositories/SUSE:/ALP:/PUBLISH/images/ALP-VM.x86_64-0.0.1-kvm-Build15.17.qcow2

    And for the encrypted image:

    > curl -LO https://download.opensuse.org/repositories/SUSE:/ALP:/PUBLISH/images/ALP-VM.x86_64-0.0.1-kvm_encrypted-Build15.18.qcow2
  2. Start Virtual Machine Manager, select File › New VM and Import existing disk image. Confirm with Forward.

  3. Specify the path to the ALP disk image that you previously downloaded and the type of linux OS you are deploying, for example, Generic Linux 2020. Confirm with Forward.

  4. Specify the amount of memory and number of processors that you want to assign to the ALP virtual machine and confirm with Forward.

  5. Specify the name for the virtual machine and the network to be used.

  6. If you are deploying an encrypted ALP image, perform these additional steps:

    1. Enable Customize configuration before install and confirm with Finish.

    2. Click Overview from the left menu and change the boot method from BIOS to UEFI for secure boot. Confirm with Apply.

      Set UEFI firmware for the encrypted ALP image
      Figure 2.1: Set UEFI firmware for the encrypted ALP image
    3. Add a Trusted Platform Module (TPM) device. Click Add Hardware, select TPM from the left menu, and select the Emulated type.

      Add emulated TPM device
      Figure 2.2: Add emulated TPM device

      Confirm with Finish and start the ALP deployment by clicking Begin Installation from the top menu.

    1. If you want to deploy ALP with only minimal setup options, confirm with Finish. The ALP disk image will be booted and JeOS Firstboot will take care of the deployment. Refer to Section 2.5.4, “Deploying ALP with JeOS Firstboot” for next steps.

    2. If you want to specify detailed deployment options, you need to use Ignition or Combustion tools to supply your setup during the disk image boot process. For more details, refer to Section 2.6, “Configuring with Ignition” and Section 2.7, “Configuring with Combustion”.

2.5.4 Deploying ALP with JeOS Firstboot

When booting the ALP raw image for the first time, JeOS Firstboot enables you to perform a minimal configuration of your system:

  1. After booting the ALP disk image, you will be presented with a bootloader screen. Select ALP and confirm with Enter.

    ALP boot screen
    Figure 2.3: ALP boot screen
  2. JeOS Firstboot displays a welcome screen. Confirm with Enter.

    JeOS Firstboot screen
    Figure 2.4: JeOS Firstboot screen
  3. On the next screens, select keyboard, confirm the license agreement, and select the time zone.

  4. In the Enter root password dialog window, enter a password for the root and confirm it.

    Enter root password
    Figure 2.5: Enter root password
  5. When deploying with an encrypted disk, follow these additional steps:

    1. Select the desired protection method and confirm with OK.

      Select method for encryption
      Figure 2.6: Select method for encryption
    2. Enter a recovery password for LUKS encryption and retype it. The root file system re-encryption will begin.

  6. ALP is successfully deployed using a minimal initial configuration.

2.5.5 Summary

After the deployment of ALP is finished, you are presented with the login prompt. Log in as root, and you are ready to set up the system and install additional workloads.

2.5.6 Next steps

Configuring with Ignition

2.6.1 What is Ignition?

Ignition is a provisioning tool that enables you to configure a system according to your specification on the first boot.

2.6.2 How does Ignition work?

When the system is booted for the first time, Ignition is loaded as part of an initramfs and searches for a configuration file within a specific directory (on a USB flash disk, or you can provide a URL). All changes are performed before the kernel switches from the temporal file system to the real root file system (before the switch_root command is issued).

Ignition uses a configuration file in the JSON format named config.ign. For the purpose of better human readability, you can create a YAML file and convert this file to JSON. For details, refer to 'Task: Converting YAML file into JSON'.

2.6.2.1 config.ign

When installing on bare metal, the configuration file config.ign must reside in the ignition subdirectory on the configuration media labeled ignition. The directory structure must look as follows:

<root directory>
└── ignition
    └── config.ign

If you intend to configure a virtual machine with Virtual Machine Manager (libvirt), provide the path to the config.ign file in its XML definition, for example:

<domain ... >
  <sysinfo type="fwcfg">
    <entry name="opt/com.coreos/config" file="/location/to/config.ign"/>
  </sysinfo>
</domain>

The config.ign contains various data types: objects, strings, integers, booleans and lists of objects. For a complete specification, refer to Ignition specification v3.3.0.

The version attribute is mandatory and in case of ALP, its value must be set either to 3.3.0 or to any lower version. Otherwise, Ignition will fail.

If you want to log in to your system as root, you must at least include a password for root. However, it is recommended to establish access via SSH keys. To configure a password, make sure to use a secure one. If you use a randomly generated password, use at least 10 characters. If you create your password manually, use even more than 10 characters and combine uppercase and lowercase letters and numbers.

Converting YAML formatted files into JSON

2.6.4.1 Introduction

JSON is a universal file format for storing structured data. Applications, for example, Ignition, use it to store and retrieve their configuration. Because JSON's syntax is complex and hard to read for human beings, you can write the configuration in a more friendly format called YAML and then convert it into JSON.

2.6.4.2 Converting YAML files into JSON format

The tool that converts Ignition-specific vocabularies in YAML files into JSON format is butane. It also verifies the syntax of the YAML file to catch potential errors in the structure. For the latest version of butane, add the following repository:

> sudo  zypper ar -f \
  https://download.opensuse.org/repositories/devel:/kubic:/ignition/openSUSE_Tumbleweed/ \
  devel_kubic_ignition

Replace openSUSE_Tumbleweed with one of the following (depending on your distribution):

  • 'openSUSE_Leap_$releasever'

  • 15.3

Now you can install the butane tool:

> sudo  zypper ref && zypper in butane

After the installation is complete, you can invoke butane by running:

>  butane -p -o config.ign config.fcc
  • config.fcc is the path to the YAML configuration file.

  • config.ign is the path to the output JSON configuration file.

  • The -p command option adds line breaks to the output file and thus makes it more readable.

2.6.4.3 Summary

After you completed the described steps, you can write and store configuration files in YAML format while providing them in JSON format if applications, for example, Ignition, require it.

Ignition configuration examples

2.6.5.1 Configuration examples in YAML

This section will provide you with some common examples of the Ignition configuration in the YAML format. Note that Ignition does not accept configuration in the YAML format but rather JSON. To convert a YAML file to the JSON format, use the butane tool as described in Section 2.6.4.1, “Introduction”.

Note
Note: The version attribute is mandatory

Each config.fcc must include version 1.4.0 or lower that is then converted to the corresponding Ignition specification.

2.6.5.1.1 Storage configuration

The storage attribute is used to configure partitions, RAID, define file systems, create files, etc. To define partitions, use the disks attribute. The filesystems attribute is used to format partitions and define mount points of particular partitions. The files attribute can be used to create files in the file system. Each of the mentioned attributes is described in the following sections.

2.6.5.1.1.1 The disks attribute

The disks attribute is a list of devices that enables you to define partitions on these devices. The disks attribute must contain at least one device, other attributes are optional. The following example will use a single virtual device and divide the disk into four partitions:

variant: fcos
version: 1.0.0
storage:
  disks:
    - device: "/dev/vda"
      wipe_table: true
      partitions:
       - label: root
         number: 1
         type_guid: 4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709
       - label: boot
         number: 2
         type_guid: BC13C2FF-59E6-4262-A352-B275FD6F7172
       - label: swap
         number: 3
         type_guid: 0657FD6D-A4AB-43C4-84E5-0933C84B4F4F
       - label: home
         number: 4
         type_guid: 933AC7E1-2EB4-4F13-B844-0E14E2AEF915
2.6.5.1.1.2 The raid attribute

The raid is a list of RAID arrays. The following attributes of raid are mandatory:

level

a level of the particular RAID array (linear, raid0, raid1, raid2, raid3, raid4, raid5, raid6)

devices

a list of devices in the array referenced by their absolute paths

name

a name that will be used for the md device

variant: fcos
version: 1.0.0
storage:
  raid:
    - name: system
      level: raid1
      devices:
        - "/dev/sda"
        - "/dev/sdb"
2.6.5.1.1.3 The filesystems attribute

filesystems must contain the following attributes:

device

the absolute path to the device, typically /dev/sda in case of physical disk

format

the file system format (btrfs, ext4, xfs, vfat or swap)

Note
Note

In case of ALP, the root file system must be formatted to btrfs.

The following example demonstrates using the filesystems attribute. The /opt directory will be mounted to the /dev/sda1 partition, which is formatted to btrfs. The device will not be erased.

variant: fcos
version: 1.0.0
storage:
  filesystems:
    - path: /opt
      device: "/dev/sda1"
      format: btrfs
      wipe_filesystem: false
2.6.5.1.1.4 The files attribute

You can use the files attribute to create any files on your machine. Bear in mind that if you want to create files outside the default partitioning schema, you need to define the directories by using the filesystems attribute.

In the following example, a host name is created by using the files attribute. The file /etc/hostname will be created with the alp-1 host name:

variant: fcos
version: 1.0.0
storage:
  files:
    - path: /etc/hostname
      mode: 0644
      overwrite: true
      contents:
        inline: "alp-1"
2.6.5.1.1.5 The directories attribute

The directories attribute is a list of directories that will be created in the file system. The directories attribute must contain at least one path attribute.

variant: fcos
version: 1.0.0
storage:
  directories:
    - path: /home/tux
      user:
        name: tux
2.6.5.1.2 Users administration

The passwd attribute is used to add users. If you intend to log in to your system, create root and set the root's password and/or add the SSH key to the Ignition configuration. You need to hash the root password, for example by using the openssl command:

 openssl passwd -6

The command creates a hash of the password you chose. Use this hash as the value of the password_hash attribute.

variant: fcos
version: 1.0.0
passwd:
  users:
   - name: root
     password_hash: "$6$PfKm6Fv5WbqOvZ0C$g4kByYM.D2B5GCsgluuqDNL87oeXiHqctr6INNNmF75WPGgkLn9O9uVx4iEe3UdbbhaHbTJ1vpZymKWuDIrWI1"
     ssh_authorized_keys:
       - ssh-rsa long...key user@host

The users attribute must contain at least one name attribute. ssh_authorized_keys is a list of ssh keys for the user.

2.6.5.1.3 Enabling systemd services

You can enable systemd services by specifying them in the systemd attribute.

variant: fcos
version: 1.0.0
systemd:
  units:
  - name: sshd.service
    enabled: true

The name must be the exact name of a service to be enabled (including the suffix).

Configuring with Combustion

2.7.1 What is Combustion?

Combustion is a dracut module that enables you to configure your system on the first boot. You can use Combustion, for example, to change the default partitions, set user passwords, create files, or install packages.

2.7.2 How does Combustion work?

Combustion is invoked after the ignition.firstboot argument is passed to the kernel command line. Combustion reads a provided file named script, executes included commands, and thus performs changes to the file system. If script includes the network flag, Combustion tries to configure the network. After /sysroot is mounted, Combustion tries to activate all mount points in /etc/fstab and then calls transactional-update to apply other changes, for example, setting root password or installing packages.

2.7.2.1 The script file

When installing on bare metal, the configuration file script must reside in the combustion subdirectory on the configuration media labeled combustion. The directory structure must look as follows:

<root directory>
└── combustion
    └── script
    └── other files

If you intend to configure a virtual machine with Virtual Machine Manager (libvirt), provide the path to the script file in its XML definition, for example:

<domain ... >
  <sysinfo type="fwcfg">
    <entry name="opt/org.opensuse.combustion/script" file="/location/to/script"/>
  </sysinfo>
</domain>
Tip
Tip: Using Combustion together with Ignition

Combustion can be used along with Ignition. If you intend to do so, label your configuration medium ignition and include the ignition directory with the config.ign to your directory structure as shown below:

<root directory>
└── combustion
    └── script
    └── other files
└── ignition
    └── config.ign

In this scenario, Ignition runs before Combustion.

Combustion configuration examples

2.7.4.1 The script configuration file

The script configuration file is a set of commands that are parsed and executed by Combustion in a transactional-update shell. This article provides examples of configuration tasks performed by Combustion.

Important
Important: Include interpreter declaration

As the script file is interpreted by Bash, always start the file with the interpreter declaration at its first line:

#!/usr/bin/bash

To log in to your system, include at least the root password. However, it is recommended to establish the authentication using SSH keys. If you need to use a root password, make sure to configure a secure password. If you use a randomly generated password, use at least 10 characters. If you create your password manually, use even more than 10 characters and combine uppercase and lowercase letters and numbers.

2.7.4.1.1 Network configuration

To configure and use the network connection during the first boot, add the following statement to script:

# combustion: network

Using this statement will pass the rd.neednet=1 argument to dracut. If you do not use the statement, the system will be configured without any network connection.

2.7.4.1.2 Partitioning

ALP raw images are delivered with a default partitioning scheme as described in Section 2.3, “Default partitioning”. You might want to use a different partitioning. The following set of example snippets moves the /home to a different partition.

Note
Note: Performing changes outside of directories included in snapshots

The following script performs changes that are not included in snapshots. If the script fails and the snapshot is discarded, some changes remain visible and cannot be reverted, for example, the changes to the /dev/vdb device.

The following snippet creates a GPT partitioning schema with a single partition on the /dev/vdb device:

sfdisk /dev/vdb <<EOF
label: gpt
type=linux
EOF

partition=/dev/vdb1

The partition is formatted to BTRFS:

wipefs --all ${partition}
mkfs.btrfs ${partition}

Possible content of /home is moved to the new /home folder location by the following snippet:

mount /home
mount ${partition} /mnt
rsync -aAXP /home/ /mnt/
umount /home /mnt

The snippet below removes an old entry in /etc/fstab and creates a new entry:

awk -i inplace '$2 != "/home"' /etc/fstab
echo "$(blkid -o export ${partition} | grep ^UUID=) /home btrfs defaults 0 0" >>/etc/fstab
2.7.4.1.3 Setting a password for root

Before you set the root password, generate a hash of the password, for example, by using the openssl passwd -6. To set the password, add the following to the script:

echo 'root:$5$.wn2BZHlEJ5R3B1C$TAHEchlU.h2tvfOpOki54NaHpGYKwdNhjaBuSpDotD7' | chpasswd -e
2.7.4.1.4 Adding SSH keys

The following snippet creates a directory to store the root's SSH key and then copies the public SSH key located on the configuration device to the authorized_keys file.

mkdir -pm700 /root/.ssh/
cat id_rsa_new.pub >> /root/.ssh/authorized_keys
Note
Note

The SSH service must be enabled in case you need to use remote login via SSH. For details, refer to Section 2.7.4.1.5, “Enabling services”.

2.7.4.1.5 Enabling services

To enable system services, for example, the SSH service, add the following line to script:

systemctl enable sshd.service
2.7.4.1.6 Installing packages
Important
Important: Network connection and registering your system may be necessary

As some packages may require additional subscription, you may need to register your system beforehand. An available network connection may also be needed to install additional packages.

During the first boot configuration, you can install additional packages to your system. For example, you can install the vim editor by adding:

zypper --non-interactive install vim-small
Note
Note

Bear in mind that you will not be able to use zypper after the configuration is complete and you boot to the configured system. To perform changes later, you must use the transactional-update command to create a changed snapshot.