Documentation: The reset and reconfiguration procedure is unclear about where it pulls the ignition file from.

[PackElend]

Hello,
Before I go into details, I will explain the background.
I started to familiarise myself with Flatcar Provisioning by setting up a simple instance on bare metal using the installer script, as described in Installing Flatcar Container Linux to disk | Flatcar Container Linux.

My configuration file is quite simple:

variant: flatcar
version: 1.1.0

passwd:
  users:
    - name: admin
      password_hash: "$6$rounds=4096$1s..."
      ssh_authorized_keys:
        - "ssh-ed25519 AAAA..."
      groups: ["sudo"]

As I read in the documentation about Customizing Flatcar | Flatcar Container Linux, I thought I could easily adapt the configuration by adapting the Ignition file and rebooting. This way, I wouldn't need to consider what I might need for future use cases.
(In addition, I thought Docker Compose was preinstalled.)

Going deeper with flatcar I noted it is not that simple:

• New Package Request: docker compose #894 but there is Docker-compose sysext | sysext-bakery
• Flatcar Container Linux startup process | Flatcar Container Linux --> reprovisioning

From that, I gathered that there is an option to add Docker Compose, but it is quite a long script. At first glance, I understood that I could extend a running instance. This is particularly due to the 'How do I use sysexts?' section of the Overview | sysext-bakery, which explains how to add scripts to a running instance. However, I cannot find any information about 'systemd-sysupdate' in the Flatcar Container Linux | Flatcar Container Linux. Therefore, I concluded that the only option to avoid losing my Docker Volumes when Installing Flatcar Container Linux to disk | Flatcar Container Linux again is to reprovision.

---

This leads me to the following questions:

1. is the only option to extend a running instance to reprovision?
2. if 1. is wrong, how to extend a life system?
3. in addtion to 2.: using System Extensions for Flatcar?
4. Where is the ignition file used for reprovisioning?
   I could only find indirect information on that: that there might be something in /usr/share/oem/. I came across this information in the Notes for distributors | Flatcar Container Linux and simply browsed /usr/share/oem/` to find the file /usr/share/oem/config.ign by coincidence.
   Finding the same full path of this file in Booting Flatcar Container Linux via PXE | Flatcar Container Linux and flatcar-install script gives me confidence that this is the file I'm looking for.
   Further conformation is given by
   1. iPXE - open source boot firmware [howto:flatcar]
   2. Installing Flatcar Container Linux on Linode | Scott's Blog
   3. and somehow Immutable_Infrastructure_with_Flatcar_Container_Linux.pdf
5. can I modify it?
   It is located in /usr what is read-only according to Adding disk space to your Flatcar Container Linux machine | Flatcar Container Linux
   1. are the side-effects as described in Technical Details for Manual Ignition Re-runs prevented if I do e.g.

   sudo flatcar-reset --keep-machine-id --keep-paths '/etc/ssh/ssh_host_.*' /var/log
   sudo systemctl reboot
   

---

I'm willing to contribute to the documention by doing a PR as happening in flatcar/flatcar-website#489 (review)

[pothos]

Hi, good to write questions here, this indicates that the docs can become better ;)

is the only option to extend a running instance to reprovision?

You can do manual changes with SSH and create the files the same way Ignition would do.

Where is the ignition file used for reprovisioning?

While you can directly place the JSON file as /oem/config.ign and then touch /boot/flatcar/first_boot before rebooting to re-run Ignition, this creates files again but doesn't reprovision and I rather recommend you to run flatcar-reset with --ignition-file <FILE> as argument which also takes care of handling the side effects and other tricky things but you need to decide whether to throw all instance data away or keep a selective list of paths.

So, in summary, it seems all you need is to extend your flatcar-reset invocation with the --ignition-file flag.

[PackElend]

Thx
I'm happy to help 😆

The most important answer is given sharing the ignition flag

But some parts of your answer raises other questions.
I'll pose them hopefully later today, I'm currently on the move.

[PackElend]

I start with the simple questions

1. What is the purpose of /usr/share/oem
2. Is it just a copy of the used ignition at boot ?
3. Why does only create files and does not reprovision? Isn't that happening at first boot? https://www.flatcar.org/docs/latest/provisioning/ignition/boot-process/#ignition let me thing so

[pothos]

The /oem (/usr/share/oem is a symlink) partition can hold an ignition config that will be picked up at boot. Normally the cloud provides one through a metadata server that gets queried first.

I meant that only running Ignition again will not delete old state, for that you need to use flatcar-reset to delete old state and run Ignition again.

[PackElend]

The /oem (/usr/share/oem is a symlink) partition can hold an ignition config that will be picked up at boot.

is that the only place where it looks for an ignition config?

Normally the cloud provides one through a metadata server that gets queried first.

I assume that is defined during very first provisioning but where is that information stored for later flatcar-reset runs?
The OEM ID is mentioned in different locations in the documentation, which seems to act as a trigger for searching for configuration files, etc.
I cannot find any specific information about where it is stored or what it depends on.

---

I'm asking these questions as I hope to write a little walkthrough guide later, from the first simple provisioning to extending a base configuration.
In such a guide, it helps to understand what is happening behind the scenes and to be able to refer to the right chapter in the documentation. It may be that some parts of them need refreshing as well :) .

---

For later stages of extending the configuration, I simply copy and paste lines such as [Docker-compose sysext | sysext-bakery] (https://flatcar.github.io/sysext-bakery/docker_compose/) which are not present in my base configuration?
update 20260103
yes that is the trick, will see if auto update will push it to v5.0.1

admin@localhost ~ $ docker compose version
Docker Compose version v5.0.0

The only issue here is that it is clear which expression to use for Release docker-compose-5.0.1 · flatcar/sysext-bakery but there is nothing like this in Release docker-compose · flatcar/sysext-bakery.
I assume the second is rather a kind of change log?