Config transpiler overview

The Config Transpiler, ct, is the utility responsible for transforming a user-provided Container Linux Configuration into an Ignition configuration. The resulting Ignition config can then be provided to a Container Linux machine when it first boots in order to provision it.

The Container Linux Config is intended to be human-friendly, and is thus in YAML. The syntax is rather forgiving, and things like references and multi-line strings are supported.

The resulting Ignition config is very much not intended to be human-friendly. It is an artifact produced by ct that users should simply pass along to their machines. JSON was chosen over a binary format to make the process more transparent and to allow power users to inspect/modify what ct produces, but it would have worked fine if the result from ct had not been human readable at all.

Why a two-step process?

There are a couple factors motivating the decision to not incorporate support for Container Linux Configs directly into the boot process of Container Linux (as in, the ability to provide a Container Linux Config directly to a booting machine, instead of an Ignition config).

Tell me more about Ignition

Ignition is the utility inside of a Container Linux image that is responsible for setting up a machine. It takes in a configuration, written in JSON, that instructs it to do things like add users, format disks, and install systemd units. The artifacts that ct produces are Ignition configs. All of this should be an implementation detail however, users are encouraged to write Container Linux Configs for ct, and to simply pass along the produced JSON file to their machines.

How similar are Container Linux Configs and Ignition configs?

Some features in Container Linux Configs and Ignition configs are identical. Both support listing users for creation, systemd unit dropins for installation, and files for writing.

All of the differences stem from the fact that Ignition configs are distribution agnostic. An Ignition config can't just tell Ignition to enable etcd, because Ignition doesn't know what etcd is. The config must tell Ignition what systemd unit to enable, and provide a systemd dropin to configure etcd.

ct on the other hand does understand the specifics of Container Linux. A user can merely specify an etcd version and some etcd options, and ct knows that there's a unit called etcd-member already on the system it can enable. It knows what options are supported by etcd, so it can sanity check them for the user. It can then generate an appropriate systemd dropin with the user's options, and provide Ignition the level of verbosity it needs, that would be tedious for a human to create.