Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Linux Enterprise Micro 5.1

7 Configuring with Ignition Edit source

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

7.1 About Ignition Edit source

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 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 7.2.1, “Converting YAML fcc file to JSON ign.

7.2 config.ign Edit source

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

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

In case 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. Though it is recommended to establish access via SSH keys. In case you want to configure a password, make sure to use a secure one. In case 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.

7.2.1 Converting YAML fcc file to JSON ign Edit source

To make the Ignition configuration more human-readable, you can use a two phase configuration. At first you prepare your configuration in YAML as a fcc file and then you 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:

tux > 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:

tux > sudo  zypper in butane

Now you can invoke butane by running:

tux >  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 lines breaks to the output file and thus makes it more readable.

7.2.2 YAML configuration examples Edit source

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.

7.2.2.1 Storage configuration Edit source

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 following sections.

7.2.2.1.1 The disks attribute Edit source

The disks attributes 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
7.2.2.1.2 The raid attribute Edit source

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"
7.2.2.1.3 The filesystem attribute Edit source

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
7.2.2.1.4 The files attribute Edit source

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"
7.2.2.1.5 The directories attribute Edit source

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

7.2.2.2 Users administration Edit source

For adding users the passwd attribute is used. 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, by using for example 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.1.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.

7.2.2.3 Enabling systemd services Edit source

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

Print this page