mirror of
https://github.com/outbackdingo/matchbox.git
synced 2026-01-27 10:19:35 +00:00
3893b7f44d
* 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
186 lines
8.2 KiB
Markdown
186 lines
8.2 KiB
Markdown
# matchbox
|
|
|
|
`matchbox` is an HTTP and gRPC service that renders signed [Ignition configs](https://coreos.com/ignition/docs/latest/what-is-ignition.html), [cloud-configs](https://coreos.com/os/docs/latest/cloud-config.html), network boot configs, and metadata to machines to create CoreOS Container Linux clusters. `matchbox` maintains **Group** definitions which match machines to *profiles* based on labels (e.g. MAC address, UUID, stage, region). A **Profile** is a named set of config templates (e.g. iPXE, GRUB, Ignition config, Cloud-Config, generic configs). The aim is to use Container Linux's early-boot capabilities to provision Container Linux machines.
|
|
|
|
Network boot endpoints provide PXE, iPXE, GRUB support. `matchbox` can be run a binary or as a container.
|
|
|
|
|
|
|
|
## Getting started
|
|
|
|
Get started running `matchbox` on your Linux machine, with Docker.
|
|
|
|
* [matchbox with Docker](getting-started-docker.md)
|
|
|
|
## Flags
|
|
|
|
See [configuration](config.md) flags and variables.
|
|
|
|
## API
|
|
|
|
* [HTTP API](api-http.md)
|
|
* [gRPC API](https://godoc.org/github.com/poseidon/matchbox/matchbox/client)
|
|
|
|
## Data
|
|
|
|
A `Store` stores machine Groups, Profiles, and associated Ignition configs, cloud-configs, and generic configs. By default, `matchbox` uses a `FileStore` to search a `-data-path` for these resources.
|
|
|
|
Prepare `/var/lib/matchbox` with `groups`, `profile`, `ignition`, `cloud`, and `generic` subdirectories. You may wish to keep these files under version control.
|
|
|
|
```
|
|
/var/lib/matchbox
|
|
├── cloud
|
|
│ ├── cloud.yaml.tmpl
|
|
│ └── worker.sh.tmpl
|
|
├── ignition
|
|
│ └── worker.ign
|
|
│ └── butane.yaml.tmpl
|
|
│ └── butane.yaml
|
|
├── generic
|
|
│ └── config.yaml
|
|
│ └── setup.cfg
|
|
│ └── datacenter-1.tmpl
|
|
├── groups
|
|
│ └── default.json
|
|
│ └── node1.json
|
|
│ └── us-central1-a.json
|
|
└── profiles
|
|
└── etcd.json
|
|
└── worker.json
|
|
```
|
|
|
|
The [examples](../examples) directory is a valid data directory with some pre-defined configs. Note that `examples/groups` contains many possible groups in nested directories for demo purposes (tutorials pick one to mount). Your machine groups should be kept directly inside the `groups` directory as shown above.
|
|
|
|
### Profiles
|
|
|
|
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": "worker.ign",
|
|
"generic_id": "some-service.cfg",
|
|
"boot": {
|
|
"kernel": "/assets/coreos/1967.3.0/coreos_production_pxe.vmlinuz",
|
|
"initrd": ["/assets/coreos/1967.3.0/coreos_production_pxe_image.cpio.gz"],
|
|
"args": [
|
|
"coreos.config.url=http://matchbox.foo:8080/ignition?uuid=${uuid}&mac=${mac:hexhyp}",
|
|
"coreos.first_boot=yes",
|
|
"coreos.autologin"
|
|
]
|
|
},
|
|
}
|
|
```
|
|
|
|
The `"boot"` settings will be used to render configs to network boot programs such as iPXE or GRUB. You may reference remote kernel and initrd assets or [local assets](#assets).
|
|
|
|
To use Ignition, set the `coreos.config.url` kernel option to reference the `matchbox` [Ignition endpoint](api-http.md#ignition-config), which will render the `ignition_id` file. Be sure to add the `coreos.first_boot` option as well.
|
|
|
|
To use cloud-config, set the `cloud-config-url` kernel option to reference the `matchbox` [Cloud-Config endpoint](api-http.md#cloud-config), which will render the `cloud_id` file.
|
|
|
|
### Groups
|
|
|
|
Groups define selectors which match zero or more machines. Machine(s) matching a group will boot and provision according to the group's `Profile`.
|
|
|
|
Create a group definition with a `Profile` to be applied, selectors for matching machines, and any `metadata` needed to render templated configs. For example `/var/lib/matchbox/groups/node1.json` matches a single machine with MAC address `52:54:00:89:d8:10`.
|
|
|
|
```json
|
|
# /var/lib/matchbox/groups/node1.json
|
|
{
|
|
"name": "node1",
|
|
"profile": "etcd",
|
|
"selector": {
|
|
"mac": "52:54:00:89:d8:10"
|
|
},
|
|
"metadata": {
|
|
"fleet_metadata": "role=etcd,name=node1",
|
|
"etcd_name": "node1",
|
|
"etcd_initial_cluster": "node1=http://node1.example.com:2380,node2=http://node2.example.com:2380,node3=http://node3.example.com:2380"
|
|
}
|
|
}
|
|
```
|
|
|
|
Meanwhile, `/var/lib/matchbox/groups/proxy.json` acts as the default machine group since it has no selectors.
|
|
|
|
```
|
|
{
|
|
"name": "etcd-proxy",
|
|
"profile": "etcd-proxy",
|
|
"metadata": {
|
|
"fleet_metadata": "role=etcd-proxy",
|
|
"etcd_initial_cluster": "node1=http://node1.example.com:2380,node2=http://node2.example.com:2380,node3=http://node3.example.com:2380"
|
|
}
|
|
}
|
|
```
|
|
|
|
For example, a request to `/ignition?mac=52:54:00:89:d8:10` would render the Ignition template in the "etcd" `Profile`, with the machine group's metadata. A request to `/ignition` would match the default group (which has no selectors) and render the Ignition in the "etcd-proxy" Profile. Avoid defining multiple default groups as resolution will not be deterministic.
|
|
|
|
#### Reserved selectors
|
|
|
|
Group selectors can use any key/value pairs you find useful. However, several labels have a defined purpose and will be normalized or parsed specially.
|
|
|
|
* `uuid` - machine UUID
|
|
* `mac` - network interface physical address (normalized MAC address)
|
|
* `hostname` - hostname reported by a network boot program
|
|
* `serial` - serial reported by a network boot program
|
|
|
|
### Config templates
|
|
|
|
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:
|
|
|
|
* [Ignition (or Butane)](ignition.md)
|
|
* [Cloud-Config](cloud-config.md)
|
|
|
|
#### Variables
|
|
|
|
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 %} -->
|
|
```
|
|
# Untyped generic config file
|
|
# Selector
|
|
{{.mac}} # 52:54:00:89:d8:10 (normalized)
|
|
# Metadata
|
|
{{.etcd_name}} # node1
|
|
{{.fleet_metadata}} # role=etcd,name=node1
|
|
# Query
|
|
{{.request.query.mac}} # 52:54:00:89:d8:10 (normalized)
|
|
{{.request.query.foo}} # some-param
|
|
{{.request.query.bar}} # b
|
|
# Special Addition
|
|
{{.request.raw_query}} # mac=52:54:00:89:d8:10&foo=some-param&bar=b
|
|
```
|
|
<!-- {% endraw %} -->
|
|
|
|
Note that `.request` is reserved for these purposes so group metadata with data nested under a top level "request" key will be overwritten.
|
|
|
|
## Assets
|
|
|
|
`matchbox` can serve `-assets-path` static assets at `/assets`. This is helpful for reducing bandwidth usage when serving the kernel and initrd to network booted machines. The default assets-path is `/var/lib/matchbox/assets` or you can pass `-assets-path=""` to disable asset serving.
|
|
|
|
```
|
|
matchbox.foo/assets/
|
|
└── coreos
|
|
└── VERSION
|
|
├── coreos_production_pxe.vmlinuz
|
|
└── coreos_production_pxe_image.cpio.gz
|
|
```
|
|
|
|
For example, a `Profile` might refer to a local asset `/assets/coreos/VERSION/coreos_production_pxe.vmlinuz` instead of `http://stable.release.core-os.net/amd64-usr/VERSION/coreos_production_pxe.vmlinuz`.
|
|
|
|
See the [get-fedora-coreos](https://github.com/poseidon/matchbox/blob/master/scripts/get-fedora-coreos) or [get-flatcar](https://github.com/poseidon/matchbox/blob/master/scripts/get-flatcar) scripts to quickly download, verify, and place image assets.
|
|
|
|
## Network
|
|
|
|
`matchbox` does not implement or exec a DHCP/TFTP server. Read [network setup](network-setup.md) or use the [poseidon/dnsmasq](../contrib/dnsmasq) image if you need a quick DHCP, proxyDHCP, TFTP, or DNS setup.
|
|
|
|
## Going further
|
|
|
|
* [gRPC API Usage](config.md#grpc-api)
|
|
* [Metadata](api-http.md#metadata)
|
|
* OpenPGP [Signing](api-http.md#openpgp-signatures)
|