Applies to SUSE Linux Enterprise Micro 5.2

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.

8.2 `config.ign` #

The config.ign is a JSON configuration file that provides prescriptions for Ignition. You can either create the file manually in JSON, or you can use the Fuel Ignition tool (https://opensuse.github.io/fuel-ignition/) to generate a basic set of prescriptions. Bear in mind that the Fuel Ignition tool does not provide a full set of options, so you might have to modify the file manually.

Alternatively, for the purpose of better human readability, you can create the file config.fcc in YAML and transpile the file to JSON. For details, refer to Section 8.2.2, “Converting YAML fcc file to JSON 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 the 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 Configuration examples #

This section will provide you with some common examples of the Ignition configuration in both JSON and YAML formats. If you create configuration in the YAML format, you need to transpile the configuration to JSON as described in Section 8.2.2, “Converting YAML fcc file to JSON ign”.

Important: Declaring content outside of default subvolumes

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.

Note: The version attribute is mandatory

Include the version specification in config.ign (version 3.3.0 or lower), resp. config.fcc (version 1.4.0 or lower).

8.2.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 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.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": "3.3.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"
                    }
                ]
            }
        ]
    }
}

The same example in the YAML format:

variant: fcos
version: 1.4.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.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": "3.3.0",
    "storage": {
        "raid": [
            {
                "name": "system",
                "level": "raid1",
                "devices": [
                    "/dev/sda",
                    "/dev/sdb"
                ]
            }
        ]
    }
}

The same example in the YAML format:

variant: fcos
version: 1.4.0
storage:
  - raid: data
    name: system
    level: raid1
    devices: "/dev/sda", "/dev/sdb"

8.2.1.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
In the 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": "3.3.0",
    "storage": {
        "filesystems": [
            {
                "path": "/opt",
                "device": "/dev/sda1",
                "format": "btrfs",
                "wipe_filesystem": false
            }
        ]
    }
}

The same example in the YAML format:

variant: fcos
version: 1.4.0
storage:
  filesystems:
    - path: /opt
      device: "/dev/sda1"
      format: btrfs
      wipe_filesystem: false

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

Note: Different numeral systems in JSON and YAML

Bear in mind that JSON uses the decimal numeral system, so the mode value is a decimal notation of the access rights. To use the octal notation, prefer YAML in this case.

{
    "variant": "fcos",
    "version": "3.3.0",
    "storage": {
        "files": [
            {
                "path": "/etc/hostname",
                "mode": 420,
                "overwrite": true,
                "contents": {
                    "inline": "slemicro-1"
                }
            }
        ]
    }
}

The same example in YAML:

variant: fcos
version: 1.4.0
storage:
  files:
    - path: /etc/hostname
      mode: 0644
      overwrite: true
      contents:
        inline: "slemicro-1"

8.2.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": "3.3.0",
    "storage": {
        "directories": [
            {
                "path": "/mnt/backup",
                "user": {
                    "name": "tux"
                }
            }
        ]
    }
}

The same example in YAML:

variant: fcos
version: 1.4.0
storage:
  directories:
    - path: /mnt/backup
      user: 
       - name: tux

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

Note: Creating other users than root

When you are creating other users than root, you need to define /home directories for the users, because these directories (usually /home/USER_NAME) are not mounted by default. Therefore, declare these directories using the storage/filesystem attribute. For example, for the tux, the example looks as follows:

        {
  "ignition": {
    "version": "3.2.0"
  },
  "passwd": {
    "users": [
      {
        "name": "tux",
        "passwordHash": "$2a$10$US9XSqLOqMmGq/OnhlVjPOwuZREh2.iEtlwD5LI7DKgV24NJU.wO6"
      }
    ]
  },
  "storage": {
    "filesystems": [
      {
        "device": "/dev/disk/by-label/ROOT",
        "format": "btrfs",
        "mountOptions": [
          "subvol=/@/home"
        ],
        "path": "/home",
        "wipeFilesystem": false
      }
    ]
  }
}

The same in YAML:

version: 1.2.0
passwd:
  users:
    - name: tux
      passwordHash: $2a$10$US9XSqLOqMmGq/OnhlVjPOwuZREh2.iEtlwD5LI7DKgV24NJU.wO6
storage:
  filesystems:
    - device: /dev/disk/by-label/ROOT
      format: btrfs
      mountOptions:
        - subvol=/@/home
      path: /home
      wipeFilesystem: false

8.2.1.3 Enabling `systemd` services #

You can enable systemd services by specifying them in the systemd attribute. The name must be the exact name of a service to be enabled (including the suffix).

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

  {
  "ignition": {
    "version": "3.0.0"
  },
  "systemd": {
    "units": [
      {
        "enabled": true,
        "name": "sshd.service"
      }
    ]
  }
}

The same example in YAML:

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

8.2.2 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 this configuration to JSON. The transpilation can be done by the butane tool.

During the transpilation, butane also verifies the syntax of the YAML file to catch potential errors in the structure. For the latest version of the 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.a

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 Configuring with Ignition #

8.1 About Ignition #

8.2 config.ign #

8.2.1 Configuration examples #

8.2.1.1 Storage configuration #

8.2.1.1.1 The disks attribute #

8.2.1.1.2 The raid attribute #

8.2.1.1.3 The filesystem attribute #

8.2.1.1.4 The files attribute #

8.2.1.1.5 The directories attribute #

8.2.1.2 Users administration #

8.2.1.3 Enabling systemd services #

8.2.2 Converting YAML fcc file to JSON ign #

8.2 `config.ign` #

8.2.1.1.1 The `disks` attribute #

8.2.1.1.2 The `raid` attribute #

8.2.1.1.3 The `filesystem` attribute #

8.2.1.1.4 The `files` attribute #

8.2.1.1.5 The `directories` attribute #

8.2.1.3 Enabling `systemd` services #

8.2.2 Converting YAML `fcc` file to JSON `ign` #