Allow passing in Butane configs directly to instances

[dustymabe]

AKA allow skipping the Butane->Ignition transpilation step.

We've received anecdotal evidence over the years that the
transpilation step where you must convert a Butane YAML configuration
into Ignition JSON before staring your CoreOS instance is a pain
for users to understand and implement. CoreOS developers also feel
this pain at times.

Should we allow for users to provide just the butane config directly to instances?

Short demo video at: https://dustymabe.com/2025/08/12/poc-leveraging-butane-during-ignition-boot/

[jlebon]

Similar sounding, but alternative half-baked proposal:

• Teach Ignition to accept YAML Ignition files
• Fold distro-agnostic sugars from Butane into the Ignition spec
• Add a concept of "Ignition plugins" where distro-specific sugars could be implemented out of tree
• Freeze Butane, eventually drop it

[dustymabe]

Similar sounding, but alternative half-baked proposal:

• Teach Ignition to accept YAML Ignition files
• Fold distro-agnostic sugars from Butane into the Ignition spec
• Add a concept of "Ignition plugins" where distro-specific sugars could be implemented out of tree
• Freeze Butane, eventually drop it

Yes. This is more the approach of folding Butane directly into Ignition and have Butane as a separate project go away.

Positives:

• May be easier to maintain longer term.
• May be easier to document for newcomers in the future.

Negatives:

• A hefty amount of work for us to realize any benefits.
• Most likely a disruption to users existing workflows.
  • i.e. If butane goes away then users will have to change what they already know into $newthing.

[dustymabe]

We discussed this during the community meeting yesterday. Everyone seemed receptive to the idea and we discussed different potential implementations, but we decided it needed more thought and agreed to discuss it again next week.

[dustymabe]

As requested in the meeting I opened a PR with the PoC code from the demo I showed:

• Support providing and translating Butane configs via library ignition#2117

[prestist]

While its really cool POC to have ignition read butane configs, it really dilutes both identities. I think it would confuse me, as now we would need to document all parts that are butane client only and then I would have to make a decision on transpileing it locally or not. Also it makes me worry about our already painful stabilization process.

From the user perspective is the pain really from the nature of having to transpile the config?

I know the burden of maintaining both the butane / igniton file has been brought up.

Would it help if we enabled butane to take ignition files and make them back to butane ones? its not a lossy transformation so it would be possible. Then ignition files could be whats stored and it would enable to user to opt in to the sugar convenience of butane and maintain both identities.

So is there really no perceived value from verifying configs before spinning hardware?
I know that you see our pattern of pre-flight testing in a lot of other IAC approaches (terriform comes to mind).

[dustymabe]

While its really cool POC to have ignition read butane configs, it really dilutes both identities.

I can see this a bit. In other words when you are providing a config to the instance, most people would probably still call it an Ignition config, but maybe you provided a Butane config. There's some ambiguity here, which isn't great, but also I think it's not too bad.

While I think there is some loss of identity here, I think for the most part if the machine does the right thing then I think the strong separate identity is less of a sticking point.

I think it would confuse me, as now we would need to document all parts that are butane client only and then I would have to make a decision on transpileing it locally or not.

Let's do that. Really the biggest thing I can think of that can't be done at runtime is the butane functionality for slurping in local files via --files-dir. What else is specific to the butane CLI?

Also it makes me worry about our already painful stabilization process.

This is a big one. I'm interested to know how much worse it would make it.

From the user perspective is the pain really from the nature of having to transpile the config?

I know the burden of maintaining both the butane / igniton file has been brought up.

It's a reasonable question to ask. The anecdotal feedback that I've heard over the years has convinced me that having this process be much different than what people are used to (cloud-init) has lost a lot of people along the way.

While the proposal here isn't that we support cloud-init directly (which maybe we should consider as well since it runs in the real root and not in the intramfs, thus it doesn't clash with Ignition). The proposal is that we make it more simple for people and I think the proposal here does that by:

1. Allowing people to never have to look at Ignition JSON directly (i.e. accepting the more user-friendly Butane natively)
2. Allowing people to commit their Butane into git and it becomes the source of truth

It's one less thing for them to worry about in their mental model. Yes, it's called Butane and there is this other thing called Ignition, etc.., but if users just pretend like this is some new-fangled cloud-init then their existing mental model works. "Ok, it's just cloud-init on steroids" and they treat it very similarly. No JSON, no transpile, just works ("hopefully, cross fingers hope to die").

Would it help if we enabled butane to take ignition files and make them back to butane ones? its not a lossy transformation so it would be possible. Then ignition files could be whats stored and it would enable to user to opt in to the sugar convenience of butane and maintain both identities.

I'm not sure I understand what you are suggesting here. Maybe an example would help?

So is there really no perceived value from verifying configs before spinning hardware? I know that you see our pattern of pre-flight testing in a lot of other IAC approaches (terriform comes to mind).

I think there is value, but as a power user (I'll describe myself as that), I want to be able to pick and choose when to use that tool. For example, I really like the idea of validating the configs before I check them into source control, but I actually want the source configs (i.e. the butane) in source control, and not the generated Ignition. i.e. I don't want two things to keep in sync. I just want the one thing that is the source of truth.

[prestist]

I can see this a bit. In other words when you are providing a config to the instance, most people would probably still call it an Ignition config, but maybe you provided a Butane config. There's some ambiguity here, which isn't great, but also I think it's not too bad.

Im not sure, am worried that complexity in the past was why people walked away and this does add another option that does impact process for a team using these tools.

Let's do that. Really the biggest thing I can think of that can't be done at runtime is the butane functionality for slurping in local files via --files-dir. What else is specific to the butane CLI?

I think so; and of course validation of the config

painful stabilization process.

This is a big one. I'm interested to know how much worse it would make it.

Not much worse, its a circular dependency though so I suspect it would be like this:

Currently we stabilize ignition, after that we release ignition, then in butane we re-vendor ignition and update targets for the new specs and then release. But now ignition would still be in a state of not able to translate to the version of stable, as its vendored butane would be outdated, so we would then have to run a re-vendor and release.

Allowing people to commit their Butane into git and it becomes the source of truth

Would it help if we enabled butane to take ignition files and make them back to butane ones? its not a lossy transformation so it would be possible. Then ignition files could be whats stored and it would enable to user to opt in to the sugar convenience of butane and maintain both identities.

I'm not sure I understand what you are suggesting here. Maybe an example would help?

Ah sorry about that. I was just thinking about the pain of maintaining two configs i.e; the user does not understand ignition config, but does understand butane. It might be helpful to have butane be able to back track an ignition config to butane.

I.e currently we can convert bu -> ign but maybe ign -> bu would be a nice feature. That way the user does not need to know how to read json or the large file. They can simply convert it back? Then in src they can have the ign file as the source of truth and when they want to edit it they can go easy mode and use butane or stay in hard mode using ign file.

[dustymabe]

Here is an example of what we could do with our mutli-arch-builders definitions if we could use butane directly:

coreos/fedora-coreos-pipeline#1196

i.e. right now there is a decent amount of transpiling that has to mappen because we merge in multiple Ignition configs into others etc.. Accepting Butane directly has the power to change some of the tedium there.

[prestist]

100% there is def a reason/desire for change, and there certainly is something that needs to be done to address it.

I think the issue with that really comes down to the fact that at some point we made an intentional decision to have butane be a client* and ignition to be an api*. This may have been an over abstraction of responsibility at the time and we certainly can backtrack that, but I dont think we do it via depending on butane in ignition.

If we really want to pursue a cloud-init like workflow I think it would be more akin to what @jlebon recommended. Though I would want to talk about that in greater detail so I have a better understanding as there would be support consequences for existing versions.