Config transpiler overview

The Container Linux config transpiler ("ct" for short) is the utility responsible for transforming a Container Linux configuration from the human-friendly, YAML form into an Ignition configuration. While it is possible to write Ignition configs directly, CoreOS recommends that this tool be used instead.

Why does Container Linux have two different configs?

Throughout the course of operating instances of Container Linux, users will notice that there are two different configs used with Container Linux: the Container Linux Config (formatted as YAML) and the Ignition Config (formatted as JSON). This may seem odd at first, but using two different configs provides both ease-of-use and power. Before elaborating on this claim, an overview of each formatted is warranted.

Overview of the config types

Container Linux Config

The Container Linux Config, as the name implies, is specific to Container Linux. It is designed to be easy to read and easy to write, something at which YAML excels. This is the config format that users are intended to directly manipulate. This config format is not explicitly versioned and instead depends on the particular version of ct that is in use. It is assumed that the user will manually keep their Container Linux Configs and ct in sync with one another. Because both the configs and ct are under the users control, this can be an atomic operation and it is unnecessary to explicitly version the Container Linux Config.

Over time, the Container Linux Config will gain more and more support for tasks and configuration specific to instances of Container Linux as well as the environment in which they run.

Ignition Config

The Ignition Config is designed to be distribution agnostic. It is not friendly for users to directly manipulate and that is by design. Ignition configs are designed to be easily generated by other tools or continuous integration pipelines. They are an intermediate language. Because there is a potential version mismatch between the tools generating Ignition configs and the machine consuming them, the configs must be explicitly versioned. This allows older tools to continue to generate valid Ignition configs even if the machine consuming them accepts newer versions of the config.

Ease-of-use and power

The pairing of the Container Linux Config and the Ignition Config allows the best of both worlds. Container Linux configs can easily be read and written by users and can be transpiled to Ignition configs via ct. Because the user must transpile the Container Linux Config before providing it to a machine, it gives ct the opportunity to validate the configuration before it's ever used. This saves a large amount of time in the long run. Instead of waiting on the order of minutes for a machine to boot, the user waits on the order of milliseconds for ct to validate and transpile the config.

The use of ct to transpile Container Linux Configs into Ignition configs allows another interesting capability. If ct knows which version of Container Linux will be receiving the config and in which environment the machine will be running, it can make specific changes to the configuration. This capability isn't leveraged today but there are plans to do so soon. A good example of this is the use of coreos-metadata. This utility, which runs on instances of Container Linux, fetches information about the machine from the hypervisor or cloud provider and makes it easily available to the services on the system. Because the type and format of this information is specific to each environment, the Ignition config must reflect the differences. When the target environment is provided to ct, it allows ct to generate an Ignition config which reflects these differences.