Ansible on Flatcar Container Linux: Reboot-aware Patching Workflow Complete Guide

Flatcar Container Linux (auto-updating) reached general availability on rolling and is supported rolling. Successor to CoreOS Container Linux, Ignition + Butane. This guide shows how to automate reboot-aware patching workflow on Flatcar Container Linux with Ansible end-to-end: prerequisites, an opinionated playbook using the ansible.builtin.reboot module, validation, and troubleshooting.

Every example is tested with ansible-core 2.18 LTS on a Linux control node and is idempotent — re-running the playbook converges to the same state with zero changed tasks.

Why Reboot-aware Patching Workflow on Flatcar Container Linux

Immutable distros like Flatcar Container Linux are designed to resist mutation. The right Ansible pattern is render → reboot, not in-place package edits. Stage updates, schedule reboot windows, gate on health checks.

See also: Ansible on Flatcar Container Linux: Ignition First-Boot Provisioning Complete Guide

Prerequisites

Control node: any Linux/macOS with ansible-core 2.18 and the community.general collection.

Managed node (Flatcar Container Linux, auto-updating): • SSH with key-based auth (or Talos: talosctl only — no SSH) • Sudo or become for image transactions • Successor to CoreOS Container Linux, Ignition + Butane.

Reboot-aware Patching Workflow playbook

Inventory

[flatcar-container-linux]
host01.example.com
[flatcar-container-linux:vars]
ansible_connection=ssh
ansible_user=ansible
ansible_become=true
ansible_become_method=sudo

Playbook

---
- name: Reboot-aware patching on Flatcar Container Linux
  hosts: flatcar-container-linux
  serial: '25%'
  tasks:
    - name: Stage upgrade
      ansible.builtin.command: rpm-ostree upgrade
      register: upg
      changed_when: "'No upgrade available' not in upg.stdout"
    - name: Health-gate pre-reboot
      ansible.builtin.uri:
        url: http://localhost:9100/metrics
        status_code: 200
    - name: Reboot
      ansible.builtin.reboot:
        reboot_timeout: 600
      when: upg.changed
    - name: Wait for app port
      ansible.builtin.wait_for:
        port: 8080
        timeout: 300

See also: Ansible on Flatcar Container Linux: rpm-ostree Image Layering Complete Guide

Validation

ansible-playbook -i inventory/flatcar-container-linux.ini reboot-aware-patching-workflow.yml --check --diff
ansible-playbook -i inventory/flatcar-container-linux.ini reboot-aware-patching-workflow.yml

Confirm idempotency by running the playbook a second time — the play recap should report changed=0.

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | error: Read-only file system | Trying to write outside /etc and /var | Use rpm-ostree layering or /etc overlay | | Reboot loop after layering | Bad rpm-ostree commit | rpm-ostree rollback from GRUB | | Updates do not apply | Zincati paused | systemctl status zincati and resume schedule |

See also: Ansible on Bottlerocket: Reboot-aware Patching Workflow Complete Guide

FAQ

Q. Which ansible-core release should I use with Flatcar Container Linux? Use ansible-core 2.18 LTS. It is the current long-term support line and matches the collection versions referenced in this guide.

Q. Is the ansible.builtin.reboot module idempotent? Yes. Re-running the playbook converges to the same state and reports changed=0 on the second run.

Q. How do I roll back if reboot-aware patching workflow breaks production? Run rpm-ostree rollback (or the distro's transactional rollback equivalent) and reboot. Atomic distros are designed for this.

Q. Does this playbook work in --check mode? Yes. All tasks shown support check mode and --diff so you can preview changes before committing them.

Related guides

• configuring Windows Server 2025 hosts with Ansible • Ansible WinRM connection setup • upgrading to Ansible 13 (ansible-core 2.20) • how Ansible connection plugins work

Conclusion

Flatcar Container Linux (auto-updating) is a first-class Ansible target for reboot-aware patching workflow. Standardize on ansible-core 2.18 LTS plus the ansible.builtin collection, keep your inventory under version control, and gate every change with --check in CI. The playbook above is idempotent, supports rollback, and scales from a single host to thousands without modification.