Skip to content

Commit 5767bc7

Browse files
dghubbledghubble
committed
Add docs tree for v0.4.0 release
1 parent 248650a commit 5767bc7

File tree

6 files changed

+142
-40
lines changed

6 files changed

+142
-40
lines changed

‎CHANGES.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ Notable changes between releases.
44

55
## Latest
66

7+
## v0.4.0
8+
79
* Migrate to the Terraform Plugin SDK ([#49](https://github.com/poseidon/terraform-provider-matchbox/pull/49))
810

911
## v0.3.0

‎README.md

Lines changed: 38 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,23 @@
11
# terraform-provider-matchbox
22

3-
`terraform-provider-matchbox` allows defining [Matchbox](https://github.com/poseidon/matchbox) Profiles and Groups in Terraform. Matchbox matches machines, by label (e.g. MAC address), to Profiles with iPXE configs, Container Linux configs, or generic free-form configs to provision clusters. Resources are created via the client certificate authenticated Matchbox API.
4-
5-
## Requirements
6-
7-
* Terraform v0.11+ [installed](https://www.terraform.io/downloads.html)
8-
* Matchbox v0.8+ [installed](https://coreos.com/matchbox/docs/latest/deployment.html)
9-
* Matchbox credentials `client.crt`, `client.key`, `ca.crt`
10-
11-
## Install
12-
13-
Add the `terraform-provider-matchbox` plugin binary for your system to the Terraform 3rd-party [plugin directory](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) `~/.terraform.d/plugins`.
14-
15-
```sh
16-
VERSION=v0.3.0
17-
wget https://github.com/poseidon/terraform-provider-matchbox/releases/download/$VERSION/terraform-provider-matchbox-$VERSION-linux-amd64.tar.gz
18-
tar xzf terraform-provider-matchbox-$VERSION-linux-amd64.tar.gz
19-
mv terraform-provider-matchbox-$VERSION-linux-amd64/terraform-provider-matchbox ~/.terraform.d/plugins/terraform-provider-matchbox_$VERSION
20-
```
21-
22-
Terraform plugin binary names are versioned to allow for migrations of managed infrastructure.
23-
24-
```
25-
$ tree ~/.terraform.d/
26-
/home/user/.terraform.d/
27-
└── plugins
28-
├── terraform-provider-matchbox_v0.2.2
29-
├── terraform-provider-matchbox_v0.2.3
30-
└── terraform-provider-matchbox_v0.3.0
31-
```
3+
`terraform-provider-matchbox` allows defining [Matchbox](https://github.com/poseidon/matchbox) Profiles and Groups in Terraform. Matchbox matches machines, by label (e.g. MAC address), to Profiles with iPXE configs, Ignition configs, or generic free-form configs to provision clusters. Resources are created via the client certificate authenticated Matchbox API.
324

335
## Usage
346

35-
[Setup](https://coreos.com/matchbox/docs/latest/network-setup.html) a PXE network boot environment and [deploy](https://coreos.com/matchbox/docs/latest/deployment.html) a Matchbox instance. Be sure to enable the gRPC API and follow the instructions to generate TLS credentials.
7+
[Setup](https://matchbox.psdn.io/network-setup/) a PXE network boot environment and [deploy](https://matchbox.psdn.io/deployment/) a Matchbox instance. Be sure to enable the gRPC API and follow the instructions to generate TLS credentials.
368

37-
Configure the Matchbox provider to use your Matchbox API endpoint and client certificate in a `providers.tf` file.
9+
Configure the Matchbox provider with the Matchbox API endpoint and client certificate (e.g. `providers.tf`).
3810

3911
```tf
4012
provider "matchbox" {
41-
version = "0.3.0"
13+
version = "0.4.0"
4214
endpoint = "matchbox.example.com:8081"
4315
client_cert = "${file("~/.matchbox/client.crt")}"
4416
client_key = "${file("~/.matchbox/client.key")}"
4517
ca = "${file("~/.matchbox/ca.crt")}"
4618
}
4719
```
4820

49-
Run `terraform init` to ensure plugin version requirements are met.
50-
51-
```
52-
$ terraform init
53-
```
54-
5521
Define a Matchbox Profile or Group resource in Terraform.
5622

5723
```tf
@@ -87,13 +53,46 @@ resource "matchbox_group" "node1" {
8753
}
8854
```
8955

56+
Run `terraform init` to ensure plugin version requirements are met.
57+
58+
```
59+
$ terraform init
60+
```
61+
9062
See [examples](https://github.com/poseidon/matchbox/tree/master/examples/terraform) for Terraform configs which PXE boot, install CoreOS, and provision entire clusters.
9163

64+
## Requirements
65+
66+
* Terraform v0.11+ [installed](https://www.terraform.io/downloads.html)
67+
* Matchbox v0.8+ [installed](https://matchbox.psdn.io/deployment/)
68+
* Matchbox credentials `client.crt`, `client.key`, `ca.crt`
69+
70+
## Install
71+
72+
Add the `terraform-provider-matchbox` plugin binary for your system to the Terraform 3rd-party [plugin directory](https://www.terraform.io/docs/configuration/providers.html#third-party-plugins) `~/.terraform.d/plugins`.
73+
74+
```sh
75+
VERSION=v0.4.0
76+
wget https://github.com/poseidon/terraform-provider-matchbox/releases/download/$VERSION/terraform-provider-matchbox-$VERSION-linux-amd64.tar.gz
77+
tar xzf terraform-provider-matchbox-$VERSION-linux-amd64.tar.gz
78+
mv terraform-provider-matchbox-$VERSION-linux-amd64/terraform-provider-matchbox ~/.terraform.d/plugins/terraform-provider-matchbox_$VERSION
79+
```
80+
81+
Terraform plugin binary names are versioned to allow for migrations of managed infrastructure.
82+
83+
```
84+
$ tree ~/.terraform.d/
85+
/home/user/.terraform.d/
86+
└── plugins
87+
├── terraform-provider-matchbox_v0.3.0
88+
└── terraform-provider-matchbox_v0.4.0
89+
```
90+
9291
## Development
9392

9493
### Binary
9594

96-
To develop the provider plugin locally, build an executable with Go 1.11+.
95+
To develop the provider plugin locally, build an executable with Go 1.12+.
9796

9897
```
9998
make

‎docs/index.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Matchbox Provider
2+
3+
`terraform-provider-matchbox` allows defining [Matchbox](https://github.com/poseidon/matchbox) Profiles and Groups in Terraform. Matchbox matches machines, by label (e.g. MAC address), to Profiles with iPXE configs, Ignition configs, or generic free-form configs to provision clusters. Resources are created via the client certificate authenticated Matchbox API.
4+
5+
## Usage
6+
7+
[Setup](https://matchbox.psdn.io/network-setup/) a PXE network boot environment and [deploy](https://matchbox.psdn.io/deployment/) a Matchbox instance. Be sure to enable the gRPC API and follow the instructions to generate TLS credentials.
8+
9+
Configure the Matchbox provider with the Matchbox API endpoint and client certificate (e.g. `providers.tf`).
10+
11+
```tf
12+
provider "matchbox" {
13+
version = "0.4.0"
14+
endpoint = "matchbox.example.com:8081"
15+
client_cert = "${file("~/.matchbox/client.crt")}"
16+
client_key = "${file("~/.matchbox/client.key")}"
17+
ca = "${file("~/.matchbox/ca.crt")}"
18+
}
19+
```
20+

‎docs/resources/group.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Group Resource
2+
3+
A Group matches (one or more) machines and declares a machine should be boot with a named `profile`.
4+
5+
```tf
6+
resource "matchbox_group" "node1" {
7+
name = "node1"
8+
profile = "${matchbox_profile.myprofile.name}"
9+
selector = {
10+
mac = "52:54:00:a1:9c:ae"
11+
}
12+
metadata = {
13+
custom_variable = "machine_specific_value_here"
14+
}
15+
}
16+
```
17+
18+
## Argument Reference
19+
20+
* `name` - Unqiue name for the machine matcher
21+
* `profile` - Name of a Matchbox profile
22+
* `selector` - Map of hardware machine selectors. See [reserved selectors](https://matchbox.psdn.io/matchbox/#reserved-selectors). An empty selector becomes a global default group that matches machines.
23+
* `metadata` - Map of group metadata (optional, seldom used)

‎docs/resources/profile.md

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Profile Resource
2+
3+
A Profile defines network boot and declarative provisioning configurations.
4+
5+
```tf
6+
variable "os_stream" {
7+
type = string
8+
description = "Fedora CoreOS release stream (e.g. testing, stable)"
9+
default = "stable"
10+
}
11+
12+
variable "os_version" {
13+
type = string
14+
description = "Fedora CoreOS version to PXE and install (e.g. 32.20200715.3.0)"
15+
}
16+
17+
locals {
18+
kernel = "https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-live-kernel-x86_64"
19+
initrd = "https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-live-initramfs.x86_64.img"
20+
}
21+
```
22+
23+
```tf
24+
resource "matchbox_profile" "worker" {
25+
name = "worker"
26+
kernel = local.kernel
27+
initrd = [
28+
local.initrd
29+
]
30+
args = [
31+
"ip=dhcp",
32+
"rd.neednet=1",
33+
"initrd=fedora-coreos-${var.os_version}-live-initramfs.x86_64.img",
34+
"coreos.inst.image_url=https://builds.coreos.fedoraproject.org/prod/streams/${var.os_stream}/builds/${var.os_version}/x86_64/fedora-coreos-${var.os_version}-metal.x86_64.raw.xz",
35+
"coreos.inst.ignition_url=${var.matchbox_http_endpoint}/ignition?uuid=$${uuid}&mac=$${mac:hexhyp}",
36+
"coreos.inst.install_dev=sda",
37+
"console=tty0",
38+
"console=ttyS0",
39+
]
40+
41+
raw_ignition = data.ct_config.worker.rendered
42+
}
43+
44+
// Transpile Fedora CoreOS config to Ignition
45+
data "ct_config" "worker" {
46+
content = file("worker.yaml")
47+
strict = true
48+
}
49+
```
50+
51+
## Argument Reference
52+
53+
* `name` - Unqiue name for the machine matcher
54+
* `kernel` - URL of the kernel image to boot
55+
* `initrd` - List of URLs to init RAM filesystems
56+
* `args` - List of kernel arguments
57+
* `raw_ignition` - Fedora CoreOS or Flatcar Linux Ignition content (see [terraform-provider-ct](https://github.com/poseidon/terraform-provider-ct))
58+
* `container_linux_config` - CoreOS Container Linux Config (CLC) (for backwards compatibility)
59+

‎matchbox/resource_profile.go

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ func resourceProfile() *schema.Resource {
4444
Optional: true,
4545
ForceNew: true,
4646
},
47-
// recommended
4847
"container_linux_config": &schema.Schema{
4948
Type: schema.TypeString,
5049
Optional: true,

0 commit comments

Comments
 (0)