F45 Change Proposal: Native Butane Config Support in Ignition (self-contained)

Wiki - https://fedoraproject.org/wiki/Changes/IgnitionNativeButaneSupport Discussion thread - https://discussion.fedoraproject.org/t/f45-change-proposal-native-butane-config-support-in-ignition-self-contained/196615 This is a proposed Change for Fedora Linux. This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee. == Summary == Enabling Ignition to natively accept Butane YAML configs in addition to Ignition JSON at first boot by merging the Butane config transpiler into the Ignition package. The <code>butane</code> CLI continues to be built from the same source and is still available as a standalone tool. == Owner == * Name: [[User:spresti| Steven Presti]] * Email: spresti@redhat.com == Detailed Description == Today, users must install the <code>butane</code> CLI tool, write a Butane YAML config, transpile it to Ignition JSON, and then pass the JSON to their instance. We think that this two-step process is the primary adoption barrier for Fedora CoreOS. This change merges the Butane codebase into the Ignition repository and modifies Ignition's config parsing to automatically detect and transpile Butane YAML configs at boot time. The implementation uses a JSON-first, Butane-fallback detection strategy: if the raw config parses as valid Ignition JSON, it is used directly; otherwise, Ignition attempts to transpile it as Butane YAML. On both failures, the original Ignition parse error is returned, preserving backward compatibility. Key design decisions: * '''Unsupported features at runtime''': Butane's <code>source: local</code> / <code>--files-dir</code> feature requires local filesystem context only available client-side and correctly returns an error at boot. The <code>butane</code> CLI remains available for local validation, <code>--strict</code>/<code>--check</code> modes, and <code>--files-dir</code> workflows. * '''OpenShift variant''': Butane's <code>openshift</code> variant produces MachineConfig YAML (not Ignition JSON), which intentionally fails Ignition's JSON parse. OpenShift provisioning goes through the Machine Config Operator and is unaffected. * '''RPM packaging''': A single ignition.spec will produce both the ignition package and a butane subpackage. The standalone butane.spec will be archived. Package names remain unchanged so existing dnf install butane workflows continue to work. == Feedback == This feature has been discussed extensively across multiple FCOS community meetings: * [https://meetbot.fedoraproject.org/meeting-1_matrix_fedoraproject-org/2026-01-14/fedora-coreos-meeting.2026-01-14-15.30.log.html 2026-01-14 community meeting] -- agreed on the merge approach * [https://meetbot-raw.fedoraproject.org/meeting-1_matrix_fedoraproject-org/2026-06-17/fedora-coreos-meeting.2026-06-17-15.30.log.html 2026-06-17 community meeting] -- agreed to pursue F45 Change Request * [https://meetbot-raw.fedoraproject.org/meeting-1_matrix_fedoraproject-org/2026-07-01/fedora-coreos-meeting.2026-07-01-15.30.log.html 2026-07-01 community meeting] -- agreed to combine ignition and butane specs, with butane as a subpackage of ignition Tracked in [https://github.com/coreos/fedora-coreos-tracker/issues/2006 coreos/fedora-coreos-tracker#2006] with 33 comments over 10 months. Key community input: * '''Alternative considered: YAML input for Ignition spec''' -- rejected because it would require Ignition spec changes and wouldn't provide Butane's sugar syntax (boot device mirroring, systemd units, etc.) * '''Alternative considered: git subtree''' -- rejected; subtrees are for maintaining active repos inside another, and Butane will be archived after the merge ([https://github.com/coreos/fedora-coreos-tracker/issues/2006#issuecomment-4750699585 travier, June 19]) == Benefit to Fedora == * '''Removes the #1 adoption barrier for Fedora CoreOS''': Users can write Butane YAML and pass it directly as instance userdata -- no toolchain installation, no transpile step, no build pipeline integration needed. * '''Simpler onboarding''': Getting started guides can show a single step (write YAML, boot instance) instead of the current three steps (install butane, write YAML, transpile, boot instance). * '''Aligns with user expectations''': Users of cloud-init and similar tools expect to pass human-readable configs directly. This brings Ignition-based systems closer to that experience. * '''Referenced configs via URL work transparently''': Butane YAML served over HTTP/S3/GCS can be used in <code>ignition.config.replace</code>/<code>merge</code> directives, enabling YAML-native config management workflows. * '''Reduced maintenance burden''': One repository, one CI pipeline, one release process instead of two. == Scope == * Proposal owners: The Ignition/Butane maintainers will merge the Butane codebase into the Ignition repository, update <code>ignition.spec</code> to produce a <code>butane</code> subpackage, archive the standalone <code>butane.spec</code>, and ensure all CI checks pass. Upstream PR: [https://github.com/coreos/ignition/pull/2235 ignition#2235]. * Other developers: No changes required from other Fedora package maintainers. The Flatcar team has reviewed the approach and confirmed compatibility. * Release engineering: N/A (not a System Wide Change) * Policies and guidelines: N/A (not needed for this Change) * Trademark approval: N/A (not needed for this Change) * Alignment with the Fedora Strategy: This change aligns with Fedora's goal of making the platform more accessible and easier to adopt. By removing a toolchain dependency from the provisioning workflow, Fedora CoreOS becomes more approachable for new users and operators. == Upgrade/compatibility impact == This change is fully backward compatible: * '''Existing Ignition JSON configs continue to work identically'''. JSON is always tried first; the Butane fallback is only attempted if JSON parsing fails. * '''No config format changes'''. Both Ignition JSON specs and Butane YAML specs remain unchanged. * '''No behavioral changes for existing deployments'''. Systems already provisioned are unaffected. * '''initrd size increase''': ~3MB. This is more than offset by complementary binary size reduction work ([https://github.com/coreos/ignition/pull/2238 ignition#2238]) which reduces the Ignition binary from 64MB to 20MB, resulting in a significantly smaller initrd than the current baseline. No manual configuration or data migration is required. == Early Testing (Optional) == Do you require 'QA Blueprint' support? N == How To Test == No special hardware is required (any x86_64 or aarch64 machine, or a cloud instance). # Write a Butane YAML config (e.g., create a user with an SSH key): <pre> variant: fcos version: 1.6.0 passwd: users: - name: core ssh_authorized_keys: - ssh-ed25519 AAAA... </pre> # Pass the YAML directly as instance userdata (no transpilation step). # Boot a Fedora CoreOS instance and verify provisioning works correctly (e.g., SSH login with the provided key succeeds). # Verify that existing Ignition JSON configs still work identically by booting an instance with a known-good JSON config. # Test that <code>ignition-validate</code> accepts both Butane YAML and Ignition JSON inputs. # Test that a Butane config using <code>source: local</code> produces a clear error at boot (expected behavior -- this feature requires the <code>butane</code> CLI). == User Experience == Users can now pass Butane YAML configs directly as instance userdata when provisioning Fedora CoreOS systems. The separate <code>butane</code> CLI transpilation step is no longer required for basic provisioning workflows. The <code>butane</code> CLI binary continues to be built and distributed for users who need: * Local config validation with <code>--strict</code> / <code>--check</code> * The <code>--files-dir</code> feature to embed local files into configs * Client-side transpilation for workflows that require Ignition JSON output == Dependencies == N/A (self-contained change). No other Fedora packages are affected. Complementary work: [https://github.com/coreos/ignition/pull/2238 ignition#2238] reduces the Ignition binary size, offsetting the size increase from embedding Butane. This is tracked separately and is not a dependency of this change. == Contingency Plan == * Contingency mechanism: Revert the merge commit and RPM spec changes. Butane remains a separate tool and users continue transpiling configs client-side (status quo). The Ignition/Butane maintainers will handle the revert. * Contingency deadline: N/A (not a System Wide Change) * Blocks release? No == Documentation == * Fedora CoreOS documentation will be updated to describe the new workflow (pass Butane YAML directly as userdata). * The <code>butane</code> CLI documentation will note that client-side transpilation is optional for basic use cases. * The Butane repository ([https://github.com/coreos/butane github.com/coreos/butane]) will be archived with a README pointing to the Ignition repository. * Upstream tracking: [https://github.com/coreos/fedora-coreos-tracker/issues/2006 coreos/fedora-coreos-tracker#2006] == Release Notes == Ignition now natively accepts Butane YAML configurations at first boot. Users can pass Butane configs directly as instance userdata without a separate transpilation step. All existing Ignition JSON configs continue to work unchanged. The <code>butane</code> CLI remains available for local validation and advanced features like <code>--files-dir</code>. -- Aoife Moloney Fedora Operations Architect Fedora Project Matrix: @amoloney:fedora.im IRC: amoloney -- _______________________________________________ devel-announce mailing list -- devel-announce@lists.fedoraproject.org To unsubscribe send an email to devel-announce-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/devel-announce@lists.fedoraproject.org Do not reply to spam, report it: https://forge.fedoraproject.org/infra/tickets/issues/new