mirror of
https://github.com/outbackdingo/matchbox.git
synced 2026-01-27 10:19:35 +00:00
Allow Butane configs with basic Go templating
* Recommend preparing Ignition configs external to Matchbox (e.g. with Terraform poseidon/terraform-provider-ct) * Document that Matchbox Rendering is discouraged * Add Butane Config support as a replacement for dropping Container Linux Config support. Perform Matchbox Go template evaluation, translation to Ignition, and parsing to a forward compatible version
This commit is contained in:
Dalton Hubble
@@ -101,9 +101,9 @@ coreos:
|
||||
command: start
|
||||
```
|
||||
|
||||
## Container Linux Config / Ignition Config
|
||||
## Ignition Config
|
||||
|
||||
Finds the profile matching the machine and renders the corresponding Ignition Config with group metadata, selectors, and query params.
|
||||
Finds the profile matching the machine and renders the corresponding Ignition for machine consumption.
|
||||
|
||||
```
|
||||
GET http://matchbox.foo/ignition?label=value
|
||||
@@ -121,11 +121,11 @@ GET http://matchbox.foo/ignition?label=value
|
||||
|
||||
```json
|
||||
{
|
||||
"ignition": { "version": "2.0.0" },
|
||||
"ignition": { "version": "3.3.0" },
|
||||
"systemd": {
|
||||
"units": [{
|
||||
"name": "example.service",
|
||||
"enable": true,
|
||||
"enabled": true,
|
||||
"contents": "[Service]\nType=oneshot\nExecStart=/usr/bin/echo Hello World\n\n[Install]\nWantedBy=multi-user.target"
|
||||
}]
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Cloud Config
|
||||
|
||||
!!! warning
|
||||
Migrate to [Container Linux Configs](container-linux-config.md). Cloud-Config support will be removed in the future.
|
||||
Migrate to [Ignition configs](ignition.md). Cloud-Config support will be removed in the future.
|
||||
|
||||
CoreOS Cloud-Config is a system for configuring machines with a Cloud-Config file or executable script from user-data. Cloud-Config runs in userspace on each boot and implements a subset of the [cloud-init spec](http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data). See the cloud-config [docs](https://coreos.com/os/docs/latest/cloud-config.html) for details.
|
||||
|
||||
|
||||
@@ -1,144 +0,0 @@
|
||||
# Container Linux Configs
|
||||
|
||||
A Container Linux Config is a YAML document which declares how Container Linux instances' disks should be provisioned on network boot and first-boot from disk. Configs can declare disk partitions, write files (regular files, systemd units, networkd units, etc.), and configure users. See the Container Linux Config [spec](https://coreos.com/os/docs/latest/configuration.html).
|
||||
|
||||
### Ignition
|
||||
|
||||
Container Linux Configs are validated and converted to *machine-friendly* Ignition configs (JSON) by matchbox when serving to booting machines. [Ignition](https://coreos.com/ignition/docs/latest/), the provisioning utility shipped in Container Linux, will parse and execute the Ignition config to realize the desired configuration. Matchbox users usually only need to write Container Linux Configs.
|
||||
|
||||
*Note: Container Linux directory names are still named "ignition" for historical reasons as outlined below. A future breaking change will rename to "container-linux-config".*
|
||||
|
||||
## Adding Container Linux Configs
|
||||
|
||||
Container Linux Config templates can be added to the `/var/lib/matchbox/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, selectors, and query params.
|
||||
|
||||
```
|
||||
/var/lib/matchbox
|
||||
├── cloud
|
||||
├── ignition
|
||||
│ └── k8s-controller.yaml
|
||||
│ └── etcd.yaml
|
||||
│ └── k8s-worker.yaml
|
||||
│ └── raw.ign
|
||||
└── profiles
|
||||
```
|
||||
|
||||
## Referencing in Profiles
|
||||
|
||||
Profiles can include a Container Linux Config for provisioning machines. Specify the Container Linux Config in a [Profile](matchbox.md#profiles) with `ignition_id`. When PXE booting, use the kernel option `coreos.first_boot=1` and `coreos.config.url` to point to the `matchbox` [Ignition endpoint](api-http.md#ignition-config).
|
||||
|
||||
## Examples
|
||||
|
||||
Here is an example Container Linux Config template. Variables will be interpreted using group metadata, selectors, and query params. Matchbox will convert the config to Ignition to serve Container Linux machines.
|
||||
|
||||
ignition/format-disk.yaml.tmpl:
|
||||
|
||||
<!-- {% raw %} -->
|
||||
```yaml
|
||||
|
||||
---
|
||||
storage:
|
||||
disks:
|
||||
- device: /dev/sda
|
||||
wipe_table: true
|
||||
partitions:
|
||||
- label: ROOT
|
||||
filesystems:
|
||||
- name: root
|
||||
mount:
|
||||
device: "/dev/sda1"
|
||||
format: "ext4"
|
||||
create:
|
||||
force: true
|
||||
options:
|
||||
- "-LROOT"
|
||||
files:
|
||||
- filesystem: root
|
||||
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
|
||||
ssh_authorized_keys:
|
||||
{{ range $element := .ssh_authorized_keys }}
|
||||
- {{$element}}
|
||||
{{end}}
|
||||
{{end}}
|
||||
```
|
||||
<!-- {% endraw %} -->
|
||||
|
||||
The Ignition config response (formatted) to a query `/ignition?label=value` for a Container Linux instance supporting Ignition 2.0.0 would be:
|
||||
|
||||
```json
|
||||
{
|
||||
"ignition": {
|
||||
"version": "2.0.0",
|
||||
"config": {}
|
||||
},
|
||||
"storage": {
|
||||
"disks": [
|
||||
{
|
||||
"device": "/dev/sda",
|
||||
"wipeTable": true,
|
||||
"partitions": [
|
||||
{
|
||||
"label": "ROOT",
|
||||
"number": 0,
|
||||
"size": 0,
|
||||
"start": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"filesystems": [
|
||||
{
|
||||
"name": "root",
|
||||
"mount": {
|
||||
"device": "/dev/sda1",
|
||||
"format": "ext4",
|
||||
"create": {
|
||||
"force": true,
|
||||
"options": [
|
||||
"-LROOT"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"files": [
|
||||
{
|
||||
"filesystem": "root",
|
||||
"path": "/home/core/foo",
|
||||
"contents": {
|
||||
"source": "data:,Example%20file%20contents%0A",
|
||||
"verification": {}
|
||||
},
|
||||
"mode": 420,
|
||||
"user": {
|
||||
"id": 500
|
||||
},
|
||||
"group": {
|
||||
"id": 500
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"systemd": {},
|
||||
"networkd": {},
|
||||
"passwd": {}
|
||||
}
|
||||
```
|
||||
|
||||
See [examples/ignition](../examples/ignition) for numerous Container Linux Config template examples.
|
||||
|
||||
### Raw Ignition
|
||||
|
||||
If you prefer to design your own templating solution, raw Ignition files (suffixed with `.ign` or `.ignition`) are served directly.
|
||||
@@ -91,7 +91,7 @@ terraform {
|
||||
|
||||
### Profiles
|
||||
|
||||
Machine profiles specify the kernel, initrd, kernel args, Ignition Config, and other configs (e.g. templated Container Linux Config, Cloud-config, generic) used to network boot and provision a bare-metal machine. The profile below would PXE boot machines using a Fedora CoreOS kernel and initrd (see [assets](api-http.md#assets) to learn about caching for speed), perform a disk install, reboot (first boot from disk), and use a [Fedora CoreOS Config](https://github.com/coreos/fcct/blob/master/docs/configuration-v1_1.md) to generate an Ignition config to provision.
|
||||
Machine profiles specify the kernel, initrd, kernel args, Ignition Config, or other configs (e.g. templated Butane Config, generic) used to network boot and provision a bare-metal machine. The profile below would PXE boot machines using a Fedora CoreOS kernel and initrd (see [assets](api-http.md#assets) to learn about caching for speed), perform a disk install, reboot (first boot from disk), and use a [Fedora CoreOS Config](https://github.com/coreos/fcct/blob/master/docs/configuration-v1_1.md) to generate an Ignition config to provision.
|
||||
|
||||
```tf
|
||||
// Fedora CoreOS profile
|
||||
|
||||
160
docs/ignition.md
Normal file
160
docs/ignition.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Ignition Configs
|
||||
|
||||
[Ignition](https://coreos.github.io/ignition/) configs define how disks should be provisioned (on network boot and first-boot from disk) to partition disks, write files (regular files, systemd units, networkd units, etc.), and configure users. Ignition is used by:
|
||||
|
||||
* Fedora CoreOS
|
||||
* RHEL CoreOS
|
||||
* Flatcar Linux
|
||||
|
||||
See the Ignition Config v3.x [specs](https://coreos.github.io/ignition/specs/) for details.
|
||||
|
||||
## Usage
|
||||
|
||||
Ignition configs can be added to the `/var/lib/matchbox/ignition` directory or in an `ignition` subdirectory of a custom `-data-path`. Ignition configs must end in `.ign` or `ignition`.
|
||||
|
||||
```
|
||||
/var/lib/matchbox
|
||||
├── ignition
|
||||
│ └── k8s-controller.ign
|
||||
│ └── k8s-worker.ign
|
||||
└── profiles
|
||||
```
|
||||
|
||||
Matchbox Profiles can set an Ignition config for provisioning machines. Specify the Ignition config in a [Profile](matchbox.md#profiles) with `ignition_id`.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "worker",
|
||||
"name": "My Profile",
|
||||
"boot": {
|
||||
...
|
||||
},
|
||||
"ignition_id": "my-ignition.ign"
|
||||
}
|
||||
```
|
||||
|
||||
When PXE booting, set kernel arguments depending on the OS (e.g. `ignition.firstboot` on FCOS, `flatcar.first_boot=yes` on Flatcar).
|
||||
|
||||
* [Fedora CoreOS](https://github.com/poseidon/matchbox/blob/main/examples/profiles/fedora-coreos.json)
|
||||
* [Flatcar Linux](https://github.com/poseidon/matchbox/blob/main/examples/profiles/flatcar.json)
|
||||
|
||||
Point the `ignition.config.url` or `flatcar.config.url` to point to the `matchbox` [Ignition endpoint](api-http.md#ignition-config).
|
||||
|
||||
Matchbox parses Ignition configs (e.g. `.ign` or `.ignition`) at spec v3.3 or below and renders to the current supported version (v3.3). This relies on Ignition's [forward compatibility](https://github.com/coreos/ignition/blob/main/config/v3_3/config.go#L61).
|
||||
|
||||
## Writing Configs
|
||||
|
||||
Ignition configs can be prepared externally and loaded via the gRPC API, rather than writing Ignition by hand.
|
||||
|
||||
### Terraform
|
||||
|
||||
Terraform can be used to prepare Ignition configs, while providing integrations with external systems and rich templating. Using tools like [poseidon/terraform-provider-ct](https://github.com/poseidon/terraform-provider-ct), you can write Butane config (an easier YAML format), validate configs, and load Ignition into Matchbox ([examples](https://github.com/poseidon/matchbox/tree/main/examples/terraform)).
|
||||
|
||||
Define a Butane config for Fedora CoreOS or Flatcar Linux:
|
||||
|
||||
```yaml
|
||||
variant: fcos
|
||||
version: 1.4.0
|
||||
passwd:
|
||||
users:
|
||||
- name: core
|
||||
ssh_authorized_keys:
|
||||
- ssh-key foo
|
||||
```
|
||||
|
||||
```yaml
|
||||
variant: flatcar
|
||||
version: 1.0.0
|
||||
passwd:
|
||||
users:
|
||||
- name: core
|
||||
ssh_authorized_keys:
|
||||
- ssh-key foo
|
||||
```
|
||||
|
||||
Define a `ct_config` data source with strict validation. Optionally use Terraform [templating](https://github.com/poseidon/terraform-provider-ct).
|
||||
|
||||
```tf
|
||||
data "ct_config" "worker" {
|
||||
content = file("worker.yaml")
|
||||
strict = true
|
||||
pretty_print = false
|
||||
|
||||
snippets = [
|
||||
file("units.yaml"),
|
||||
file("storage.yaml"),
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then render the Butane config to Ignition and use it in a Matchbox Profile.
|
||||
|
||||
```tf
|
||||
resource "matchbox_profile" "fedora-coreos-install" {
|
||||
name = "worker"
|
||||
kernel = "/assets/fedora-coreos/fedora-coreos-${var.os_version}-live-kernel-x86_64"
|
||||
initrd = [
|
||||
"--name main /assets/fedora-coreos/fedora-coreos-${var.os_version}-live-initramfs.x86_64.img"
|
||||
]
|
||||
|
||||
args = [
|
||||
"initrd=main",
|
||||
"coreos.live.rootfs_url=${var.matchbox_http_endpoint}/assets/fedora-coreos/fedora-coreos-${var.os_version}-live-rootfs.x86_64.img",
|
||||
"coreos.inst.install_dev=/dev/vda",
|
||||
"coreos.inst.ignition_url=${var.matchbox_http_endpoint}/ignition?uuid=$${uuid}&mac=$${mac:hexhyp}",
|
||||
]
|
||||
|
||||
raw_ignition = data.ct_config.worker.rendered
|
||||
}
|
||||
```
|
||||
|
||||
See the Terraform [examples](https://github.com/poseidon/matchbox/tree/main/examples#terraform-examples) for details.
|
||||
|
||||
### Butane
|
||||
|
||||
The [Butane](https://coreos.github.io/butane/) command line tool can be used to convert Butane configs (an easier YAML format) to Ignition. Then you can use the Matchbox gRPC API to upload the rendered Ignition to Matchbox for serving to machines on boot.
|
||||
|
||||
See [examples/ignition](../examples/ignition) for Butane config examples.
|
||||
|
||||
### Matchbox Rendering
|
||||
|
||||
While Matchbox recommends preparing Ignition configs externally (e.g. using Terraform's rich templating), Matchbox does still support limited templating and translation features with a builtin Butane converter.
|
||||
|
||||
Specify a Butane config in a [Profile](matchbox.md#profiles) with `ignition_id` (file must not end in `.ign` or `.ignition`).
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "worker",
|
||||
"name": "My Profile",
|
||||
"boot": {
|
||||
...
|
||||
},
|
||||
"ignition_id": "butane.yaml"
|
||||
}
|
||||
```
|
||||
|
||||
Here is an example Butane config with Matchbox template elements. Template files may contain [Go template](https://golang.org/pkg/text/template/) elements which will be interpreted using group metadata, selectors, and query params.
|
||||
|
||||
```yaml
|
||||
variant: flatcar
|
||||
version: 1.0.0
|
||||
storage:
|
||||
files:
|
||||
- path: /var/home/core/foo
|
||||
mode: 0644
|
||||
contents:
|
||||
inline: |
|
||||
{{.example_contents}}
|
||||
|
||||
{{ if index . "ssh_authorized_keys" }}
|
||||
passwd:
|
||||
users:
|
||||
- name: core
|
||||
ssh_authorized_keys:
|
||||
{{ range $element := .ssh_authorized_keys }}
|
||||
- {{$element}}
|
||||
{{end}}
|
||||
{{end}}
|
||||
```
|
||||
|
||||
Matchbox will use the Butane library to config to the current supported Ignition version. This relies on Ignition's [forward compatibility](https://github.com/coreos/ignition/blob/main/config/v3_3/config.go#L61).
|
||||
@@ -33,9 +33,9 @@ Prepare `/var/lib/matchbox` with `groups`, `profile`, `ignition`, `cloud`, and `
|
||||
│ ├── cloud.yaml.tmpl
|
||||
│ └── worker.sh.tmpl
|
||||
├── ignition
|
||||
│ └── raw.ign
|
||||
│ └── etcd.yaml.tmpl
|
||||
│ └── simple.yaml.tmpl
|
||||
│ └── worker.ign
|
||||
│ └── butane.yaml.tmpl
|
||||
│ └── butane.yaml
|
||||
├── generic
|
||||
│ └── config.yaml
|
||||
│ └── setup.cfg
|
||||
@@ -53,14 +53,14 @@ The [examples](../examples) directory is a valid data directory with some pre-de
|
||||
|
||||
### Profiles
|
||||
|
||||
Profiles reference an Ignition config, Cloud-Config, and/or generic config by name and define network boot settings.
|
||||
Profiles reference an Ignition config, Butane Config, Cloud-Config, and/or generic config by name and define network boot settings.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "etcd",
|
||||
"name": "Container Linux with etcd2",
|
||||
"cloud_id": "",
|
||||
"ignition_id": "etcd.yaml",
|
||||
"ignition_id": "worker.ign",
|
||||
"generic_id": "some-service.cfg",
|
||||
"boot": {
|
||||
"kernel": "/assets/coreos/1967.3.0/coreos_production_pxe.vmlinuz",
|
||||
@@ -128,16 +128,16 @@ Group selectors can use any key/value pairs you find useful. However, several la
|
||||
|
||||
### Config templates
|
||||
|
||||
Profiles can reference various templated configs. Ignition JSON configs can be generated from [Container Linux Config](https://github.com/coreos/container-linux-config-transpiler/blob/master/doc/configuration.md) template files. Cloud-Config templates files can be used to render a script or Cloud-Config. Generic template files can be used to render arbitrary untyped configs (experimental). Each template may contain [Go template](https://golang.org/pkg/text/template/) elements which will be rendered with machine group metadata, selectors, and query params.
|
||||
Profiles can reference various templated configs. Ignition configs can be provided directly or rendered fro [Butane Config](https://coreos.github.io/butane/) template files. Cloud-Config templates files can be used to render a script or Cloud-Config. Generic template files can be used to render arbitrary untyped configs (experimental). Each template may contain [Go template](https://golang.org/pkg/text/template/) elements which will be rendered with machine group metadata, selectors, and query params.
|
||||
|
||||
For details and examples:
|
||||
|
||||
* [Container Linux Config](container-linux-config.md)
|
||||
* [Ignition (or Butane)](ignition.md)
|
||||
* [Cloud-Config](cloud-config.md)
|
||||
|
||||
#### Variables
|
||||
|
||||
Within Container Linux Config templates, Cloud-Config templates, or generic templates, you can use group metadata, selectors, or request-scoped query params. For example, a request `/generic?mac=52-54-00-89-d8-10&foo=some-param&bar=b` would match the `node1.json` machine group shown above. If the group's profile ("etcd") referenced a generic template, the following variables could be used.
|
||||
Within Butane Config templates, Cloud-Config templates, or generic templates, you can use group metadata, selectors, or request-scoped query params. For example, a request `/generic?mac=52-54-00-89-d8-10&foo=some-param&bar=b` would match the `node1.json` machine group shown above. If the group's profile ("etcd") referenced a generic template, the following variables could be used.
|
||||
|
||||
<!-- {% raw %} -->
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user