Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
documentation.suse.com / SUSE Linux Enterprise Micro Documentation / Deployment Guide / Pre-built image deployment / Configuring with Ignition
Applies to SUSE Linux Enterprise Micro 5.3

8 Configuring with Ignition

This chapter provides details about the Ignition provisioning tool that is used to set up a machine. Here you will learn how to provide required configuration files used for the machine definition.

8.1 About Ignition

Ignition is a provisioning tool that enables you to configure a system according to your specification on the first boot. 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. The file is called 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 Section 8.2.1, “Converting YAML fcc file to JSON ign.

8.2 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 QEMU/KVM virtual machine, provide the path to the config.ign as an attribute of the qemu command. For example:

-fw_cfg name=opt/com.coreos/config,file=PATH_TO_config.ign

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 SLE Micro, 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. If you want 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.

8.2.1 Converting YAML fcc file to JSON ign

To make the Ignition configuration more human-readable, you can use a two- phase configuration. First, prepare your configuration in YAML as a fcc file and then transpile these configuration to JSON. The transpilation can be done by the butane tool.

During the transpilation, butane also verifies syntax of the YAML file to catch potential errors in the structure. For the latest version of butane tool add a repository:

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

where DISTRIBUTION is one of the following (depending on your distribution):

  • openSUSE_Tumbleweed

  • openSUSE_Leap_$release_number

  • 15.3

Now you can install the butane tool:

> sudo  zypper in butane

Now you can invoke butane by running:

>  butane -p -o config.ign config.fcc

where:

  • 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.

8.2.2 YAML configuration examples

This section will provide you with some common examples of the Ignition configuration in the YAML format.

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.

8.2.2.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 filesystem 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.

8.2.2.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"
      wipeTable: true
      partitions: 
      	- label: root
      	  number: 1
      	  typeGuid: 4F68BCE3-E8CD-4DB1-96E7-FBCAF984B709
      	- label: boot
      	  number: 2
      	  typeGuid: BC13C2FF-59E6-4262-A352-B275FD6F7172
        - label: swap
      	  number: 3
      	  typeGuid: 0657FD6D-A4AB-43C4-84E5-0933C84B4F4F
      	- label: home
      	  number: 4
      	  typeGuid: 933AC7E1-2EB4-4F13-B844-0E14E2AEF915
8.2.2.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: data
	  name: system
	  level: raid1
	  devices: "/dev/sda", "/dev/sdb"
8.2.2.1.3 The filesystem attribute

filesystem 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 SLE Micro, the root file system must be formatted to btrfs.

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

variant: fcos
version: 1.0.0
storage:
  filesystems:
    - path: /opt
      device: "/dev/sda1"
      format: btrfs
      wipe_filesystem: false
8.2.2.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 mounted directories, you need to define the directories by using the filesystem attribute.

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

variant: fcos
version: 1.0.0
storage:
  files:
    - path: /etc/hostname
      mode: 0644
      overwrite: true
      contents:
        inline: "slemicro-1"
8.2.2.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

8.2.2.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.

8.2.2.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).