butane-init: a Cloud-Init to Butane Config Transpiler

Background

Flatcar uses Butane and Ignition for provisioning. Much of the wider ecosystem still produces cloud-config (cloud-init) YAML, which makes it harder to adopt Flatcar in environments where cloud-config is already the norm.

The Project

A transpiler in Go that converts cloud-config YAML into Butane YAML. The transpiler implements the minimum functionality needed to support ClusterAPI worker node provisioning, and to replace coreos-cloudinit In practice that limits the transpiler to basic Butane features such as users, groups, certificates, files and systemd units.

Goals and Non-Goals

• A working Go transpiler covering a documented subset of cloud-config.
• Test coverage for each supported feature, running in CI.
• End to end integration with Flatcar and ClusterAPI.
• Documentation covering supported fields and known limitations.

Usage

Build bt, then pass a cloud-config file or pipe one on standard input:

go build -o bt ./cmd/bt
bt cloud-config.yaml > butane.yaml
# or: cat cloud-config.yaml | bt -o butane.yaml

bt currently converts only the Cluster API worker users subset. A config is either converted completely or rejected; unsupported fields are never silently discarded.

cloud-config stanza	Status	Butane output
users	Supported Cluster API subset	passwd, plus generated storage.files
write_files	Unsupported	Planned storage.files
runcmd	Unsupported	Planned scripts and systemd units
bootcmd	Unsupported	Planned scripts and systemd units
ntp	Unsupported	Planned time-sync configuration
disk_setup	Unsupported	Planned storage configuration
fs_setup	Unsupported	Planned storage.filesystems
mounts	Unsupported	Planned filesystems or systemd mount units

cloud-config field	Butane output
name	passwd.users[].name
passwd	passwd.users[].password_hash
gecos	passwd.users[].gecos
homedir	passwd.users[].home_dir
shell	passwd.users[].shell
ssh_authorized_keys	passwd.users[].ssh_authorized_keys
groups	passwd.users[].groups and synthesized passwd.groups
primary_group	passwd.users[].primary_group and synthesized passwd.groups
inactive	false is a no-op; true is rejected
lock_passwd	Password locking and a generated sshd drop-in when false
sudo	A generated /etc/sudoers.d/<username> file

The new fields accept only the shapes emitted by Cluster API: groups is a comma-separated string, primary_group and sudo are non-empty strings, and inactive and lock_passwd are booleans. Referenced groups are created before users. Empty or duplicate supplementary groups are rejected, and a primary group must not also be listed as a supplementary group. If a referenced group has the same name as a configured user, that user must set primary_group explicitly to avoid colliding with Linux's implicit private-group creation.

Password hashes are locked when lock_passwd is omitted or true. When it is false, the hash remains unlocked and bt enables SSH password authentication for that user with a Flatcar sshd drop-in. An already-locked hash is rejected when lock_passwd is false. Users that request password login or sudo must have names matching ^[a-z_][a-z0-9_-]*$ so names cannot become SSH, sudoers, or path syntax.

Generated sshd and sudoers files are root-owned, mode 0600, and replace any existing file at the generated path. Sudo rules are preserved verbatim and are not checked for valid sudoers syntax. No sshd restart is needed because Ignition writes the drop-in before sshd starts.

Every non-users stanza remains unsupported. Jinja templates are not evaluated and are rejected; render them before passing the resulting cloud-config to bt.

A Flatcar Container Linux project

Flatcar Container Linux is a fully open source, minimal-footprint, secure by default and always up-to-date Linux distribution for running containers at scale.

This repository is maintained by the Flatcar community and contributors. Development and design decisions are guided by the principles of transparency, modularity, and collaboration.

Please find information on:

• Contribution Guide – how to get involved and submit patches.
• Repository Codeowners – who's assigned for contribution reviews in this repository.
• Repository Maintainers – who’s responsible for what in this repository.
• Flatcar Project Maintainers – who’s responsible for what at Flatcar.
• Governance – how decisions are made and who the stakeholders are.
• Code of Conduct – our commitment to a welcoming and inclusive community.
• LICENSE - License under which the software is released.

---

Community & Project Documentation

• Contributing Guidelines — How to contribute, find issues, and submit pull requests
• Code of Conduct — Standards for respectful and inclusive community participation
• Security Policy — How to report vulnerabilities and security-related information
• Maintainers — Current project maintainers and their responsibilities
• Governance — Project governance model, decision-making process, and roles