diff --git a/CHANGES.md b/CHANGES.md index 0b92ab30..03db65b2 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -16,6 +16,14 @@ * Error when an Ignition/Cloud-config template is rendered with a machine Group which is missing a metadata value. Previously, missing values defaulted to "no value" (#210) * Add/improve rkt, Docker, Kubernetes, and binary/systemd deployment docs +#### Changes + +* Replace Ignition YAML templates with Fuze templates (**breaking**) + - Fuze formalizes the transform from Fuze configs (YAML) to Ignition 2.0.0 (JSON) + - [Migrate from bootcfg v0.3.0](Documentation/ignition.md#migration-from-v030) + - Require CoreOS 1010.1.0 or newer + - Drop support for Ignition v1 format + #### Examples * Add self-hosted Kubernetes example (PXE boot or install to disk) diff --git a/Documentation/bootcfg.md b/Documentation/bootcfg.md index 947ba356..46557402 100644 --- a/Documentation/bootcfg.md +++ b/Documentation/bootcfg.md @@ -31,12 +31,12 @@ Prepare `/var/lib/bootcfg` with `profile`, `groups`, `ignition`, and `cloud` sub /var/lib/bootcfg ├── cloud - │   ├── cloud.yaml - │   └── worker.sh + │   ├── cloud.yaml.tmpl + │   └── worker.sh.tmpl ├── ignition - │   └── hello.json - │   └── etcd.yaml - │   └── simple_networking.yaml + │   └── raw.ign + │   └── etcd.yaml.tmpl + │   └── simple.yaml.tmpl ├── generic │   └── config.yaml │   └── setup.cfg @@ -79,7 +79,7 @@ To use Ignition, set the `coreos.config.url` kernel option to reference the `boo #### Configs -Profiles can reference various templated configs. Ignition templates can be JSON or YAML files (rendered as JSON). Cloud-Config templates can be a script or YAML file. Generic configs can be provided in any format. Each template may contain [Go template](https://golang.org/pkg/text/template/) elements which will be executed with machine Group [metadata](#groups-and-metadata). For details and examples: +Profiles can reference various templated configs. Ignition JSON configs can be generated from [Fuze config](https://github.com/coreos/fuze/blob/master/doc/configuration.md) template files. Cloud-Config templates files can be used to render a script or Cloud-Config. Generic template files configs can be used to render arbitrary untyped configs. Each template may contain [Go template](https://golang.org/pkg/text/template/) elements which will be executed with machine Group [metadata](#groups-and-metadata). For details and examples: * [Ignition Config](ignition.md) * [Cloud-Config](cloud-config.md) diff --git a/Documentation/ignition.md b/Documentation/ignition.md index 6a8de918..bf47a92e 100644 --- a/Documentation/ignition.md +++ b/Documentation/ignition.md @@ -1,42 +1,81 @@ # Ignition -Ignition is a system for declaratively provisioning disks from the initramfs, before systemd starts. It runs only on the first boot and handles formatting partitioning, writing files (systemd units, networkd units, dropins, regular files), and configuring users. See the Ignition [docs](https://coreos.com/ignition/docs/latest/) for details. +Ignition is a system for declaratively provisioning disks during the initramfs, before systemd starts. It runs only on the first boot and handles partitioning disks, formatting partitions, writing files (regular files, systemd units, networkd units, dropins), and configuring users. See the Ignition [docs](https://coreos.com/ignition/docs/latest/) for details. -Ignition configurations are JSON documents, but with bootcfg you may write and maintain YAML templates which will be converted to JSON when requested. Templating allows values to be substituted to facilitate reuse. +## Fuze Configs -Ignition template files can be added in the `/var/lib/bootcfg/ignition` directory or in an `ignition` subdirectory of a custom `-data-path`. Template files may contain [Go template](https://golang.org/pkg/text/template/) elements which will be evaluated with Group `metadata` and should render to JSON or YAML (which will be returned by `bootcfg` as JSON after processing). +Ignition 2.0.0+ configs are versioned, *machine-friendly* JSON documents (which contain encoded file contents). Operators should write and maintain configs in a *human-friendly* format, such as CoreOS [fuze](https://github.com/coreos/fuze) configs. As of `bootcfg` v0.4.0, Fuze configs are the primary way to use CoreOS Ignition. + +Fuze formalizes the transform from a [Fuze config](https://github.com/coreos/fuze/blob/master/doc/configuration.md) (YAML) to Ignition. Fuze allows services (like `bootcfg`) to negotiate versions and serve Ignition configs to different CoreOS clients. That means, you can write a Fuze config in YAML and serve Ignition to different CoreOS instances, even as we update the Ignition version shipped in the OS. + +Fuze automatically handles file content encoding so that you can continue to write and maintain readable inline file contents. + +``` +... +files: + - path: /etc/foo.conf + filesystem: rootfs + contents: + inline: | + foo bar +``` + +Fuze can also patch some bugs in shipped Ignition versions and validate configs for errors. + +## Adding Fuze Configs + +Fuze template files can be added in the `/var/lib/bootcfg/ignition` directory or in an `ignition` subdirectory of a custom `-data-path`. Template files may contain [Go template](https://golang.org/pkg/text/template/) elements which will be evaluated with Group `metadata` and should render to a Fuze config. /var/lib/bootcfg ├── cloud ├── ignition - │   └── simple.json + │   └── raw.ign │   └── etcd.yaml │   └── etcd-proxy.yaml │   └── networking.yaml └── profiles -Reference an Ignition config in a [Profile](bootcfg.md#profiles). When PXE booting, use the kernel option `coreos.first_boot=1` and `coreos.config.url` to point to the `bootcfg` [Ignition endpoint](api.md#ignition-config). +### Referencing -## Configs +Reference an Fuze config in a [Profile](bootcfg.md#profiles) with `ignition_id`. When PXE booting, use the kernel option `coreos.first_boot=1` and `coreos.config.url` to point to the `bootcfg` [Ignition endpoint](api.md#ignition-config). -Here is an example Ignition template for static networking. This template will be rendered into YAML, using metadata (from a Group) to fill in the template values. Once templated, the YAML is then tranformed into standard JSON. All of this happens at query time, so that when Ignition queries bootcfg the only thing it sees is the final standard JSON output. +## Examples -ignition/network.yaml.tmpl: +See [examples/ignition](../examples/ignition) for numerous Fuze template examples. + +Here is an example Fuze template. This template will be rendered into a Fuze config (YAML), using metadata (from a Group) to fill in the template values. At query time, `bootcfg` transforms the Fuze config to Ignition for clients. + +ignition/format-disk.yaml.tmpl: --- - ignition_version: 1 - networkd: - units: - - name: 10-static.network - contents: | - [Match] - MACAddress={{.mac}} - [Network] - Gateway={{.networkd_gateway}} - DNS={{.networkd_dns}} - Address={{.networkd_address}} - {{ if .ssh_authorized_keys }} + storage: + disks: + - device: /dev/sda + wipe_table: true + partitions: + - label: ROOT + filesystems: + - name: rootfs + mount: + device: "/dev/sda1" + format: "ext4" + create: + force: true + options: + - "-LROOT" + files: + - filesystem: rootfs + path: /home/core/foo + mode: 0644 + user: + id: 500 + group: + id: 500 + contents: + inline: | + {{.example_contents}} + {{ if index . "ssh_authorized_keys" }} passwd: users: - name: core @@ -46,26 +85,69 @@ ignition/network.yaml.tmpl: {{end}} {{end}} -Below is a response that you would get from making a GET request to `/ignition?mac=address` for a particular machine. As you can see, the file response is in JSON, not YAML, as Ignition is a JSON format. You can also see that the templated values such as `{{.networkd_name}}` has been filled in. +Below is the Ignition config response from `/ignition?selector=value` for a CoreOS instance supporting Ignition 2.0.0. In this case, no `"ssh_authorized_keys"` list was provided in metadata. { - "ignitionVersion": 1, - "storage": {}, - "systemd": {}, - "networkd": { - "units": [ + "ignition": { + "version": "2.0.0", + "config": {} + }, + "storage": { + "disks": [ { - "name": "00-ens3.network", - "contents": "[Match]\nName=ens3\n[Network]\nGateway=172.15.0.1\nDNS=172.15.0.3\nDNS=8.8.8.8\nAddress=172.15.0.21/16\n" + "device": "/dev/sda", + "wipeTable": true, + "partitions": [ + { + "label": "ROOT", + "number": 0, + "size": 0, + "start": 0 + } + ] + } + ], + "filesystems": [ + { + "name": "rootfs", + "mount": { + "device": "/dev/sda1", + "format": "ext4", + "create": { + "force": true, + "options": [ + "-LROOT" + ] + } + } + } + ], + "files": [ + { + "filesystem": "rootfs", + "path": "/home/core/foo", + "contents": { + "source": "data:,Example%20file%20contents%0A", + "verification": {} + }, + "mode": 420, + "user": { + "id": 500 + }, + "group": { + "id": 500 + } } ] }, + "systemd": {}, + "networkd": {}, "passwd": {} } -Note that rendered Ignition does **not** allow variables - the response has been fully rendered with `metadata` for the requesting machine. +### Raw Ignition -Ignition configs can be provided directly as JSON as well (`.ign` or `.ignition`). This is useful for simple cases or if you prefer to use your own templating solution to generate Ignition configs. This would be very similar to running your own webserver to hosting Ignition configs. +If you prefer to design your own templating solution, raw Ignition files (suffixed with `.ign` or `.ignition`) are served directly. ignition/run-hello.ign: @@ -82,7 +164,20 @@ ignition/run-hello.ign: } } -### Examples +### Migration from v0.3.0 -See [examples/ignition](../examples/ignition) for example Ignition templates. +`bootcfg` v0.3.0 and earlier accepted YAML templates and rendered them to Ignition v1 JSON. + +In v0.4.0, `bootcfg` switched to using the CoreOS [fuze](https://github.com/coreos/fuze) library, which formalizes and improves upong the YAML to Ignition JSON transform. Fuze provides better support for Ignition 2.0.0+, handles file content encoding, patches Ignition bugs, and performs better validations. + +To upgrade to bootcfg `v0.4.0`, upgrade your Ignition YAML templates to match the [Fuze config schema](https://github.com/coreos/fuze/blob/master/doc/configuration.md). CoreOS machines **must be 1010.1.0 or newer**, support for the older Ignition v1 format has been dropped. + +Typically, you'll need to do the following: + +* Remove `ignition_version: 1`, Fuze configs are versionless +* Update `filesystems` section and set the `name` +* Update `files` section to use `inline` as shown above +* Replace `uid` and `gid` with `user` and `group` objects as shown above + +Read the upstream Ignition v1 to 2.0.0 [migration guide](https://coreos.com/ignition/docs/latest/migrating-configs.html) to better understand the reasons behind Fuze's schema. diff --git a/examples/ignition/format-disk.yaml b/examples/ignition/format-disk.yaml index 5804ad68..bf47a129 100644 --- a/examples/ignition/format-disk.yaml +++ b/examples/ignition/format-disk.yaml @@ -25,7 +25,7 @@ storage: id: 500 contents: inline: | - bar + Example file contents {{ if index . "ssh_authorized_keys" }} passwd: