Upgrading Flatcar configs

Occasionally, changes are made to Flatcar Butane configs (those that specify variant: flatcar) that break backward compatibility. While this is not a concern for running machines, since Ignition only runs one time during first boot, it is a concern for those who maintain configuration files. This document serves to detail each of the breaking changes and tries to provide some reasoning for the change. This does not cover all of the changes to the spec - just those that need to be considered when migrating from one version to the next.

  1. Upgrading Flatcar configs
    1. From Version 1.0.0 to Version 1.1.0
      1. LUKS discard
      2. LUKS open options
      3. Special mode bits supported
      4. AWS S3 access point ARN support
      5. Local SSH key and systemd unit references

From Version 1.0.0 to Version 1.1.0

There are no breaking changes between versions 1.0.0 and 1.1.0 of the flatcar configuration specification. Any valid 1.0.0 configuration can be updated to a 1.1.0 configuration by changing the version string in the config.

The following is a list of notable new features.

LUKS discard

The luks section gained a new discard field. If specified and true, the LUKS volume will issue discard commands to the underlying block device when blocks are freed. This improves performance and device longevity on SSDs and space utilization on thinly provisioned SAN devices, but leaks information about which disk blocks contain data.

variant: flatcar
version: 1.1.0
storage:
  luks:
    - name: luks-static
      device: /dev/sdb
      discard: true
      key_file:
        inline: REPLACE-THIS-WITH-YOUR-KEY-MATERIAL

LUKS open options

The luks section gained a new open_options field. It is a list of options Ignition should pass to cryptsetup luksOpen when unlocking the volume. Ignition also passes --persistent, so any options that support persistence will be saved to the volume and automatically used for future unlocks. Any options that do not support persistence will only be applied to Ignition’s initial unlock of the volume.

variant: flatcar
version: 1.1.0
storage:
  luks:
    - name: luks-static
      device: /dev/sdb
      open_options:
        - "--perf-no_read_workqueue"
        - "--perf-no_write_workqueue"
      key_file:
        inline: REPLACE-THIS-WITH-YOUR-KEY-MATERIAL

Special mode bits supported

The mode field of the files and directories sections now respects the setuid, setgid, and sticky bits. Previous spec versions ignore these bits.

variant: flatcar
version: 1.1.0
storage:
  files:
    - path: /usr/local/bin/setuid
      mode: 04755
      contents:
        source: https://rootkit.example.com/setuid
  directories:
    - path: /var/local/tmp
      mode: 01777

AWS S3 access point ARN support

The sections which allow fetching a remote URL now accept AWS S3 access point ARNs (arn:aws:s3:<region>:<account>:accesspoint/<accesspoint>/object/<path>) in the source field.

variant: flatcar
version: 1.1.0
storage:
  files:
    - path: /etc/example
      mode: 0644
      contents:
        source: arn:aws:s3:us-west-1:123456789012:accesspoint/test/object/some/path

Local SSH key and systemd unit references

SSH keys and systemd units are now embeddable via file references to local files. The specified path is relative to a local files-dir, specified with the -d/--files-dir option to Butane. If no files-dir is specified, this functionality is unavailable.

variant: flatcar
version: 1.1.0
systemd:
  units:
    - name: example.service
      contents_local: example.service
    - name: example-drop-in.service
      dropins:
        - name: example-drop-in.conf
          contents_local: example.conf
passwd:
  users:
    - name: core
      ssh_authorized_keys_local:
        - id_rsa.pub