Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve deployment docs, prep for release v0.9.0 #817

Merged
merged 1 commit into from
Oct 15, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions CHANGES.md
Original file line number Diff line number Diff line change
@@ -4,13 +4,16 @@ Notable changes between releases.

## Latest

## v0.9.0

* Refresh docs and examples for Fedora CoreOS and Flatcar Linux ([#815](https://github.com/poseidon/matchbox/pull/815), [#816](https://github.com/poseidon/matchbox/pull/816))
* Update Kubernetes manifest examples ([#791](https://github.com/poseidon/matchbox/pull/791), [#817](https://github.com/poseidon/matchbox/pull/817))
* Update Matchbox container image publishing ([#795](https://github.com/poseidon/matchbox/pull/795))
* Publish Matchbox images from internal infra to Quay (`quay.io/poseidon/matchbox`)
* Update Go version from v1.13.4 to v1.14.9
* Update base image from `alpine:3.10` to `alpine:3.12` ([#784](https://github.com/poseidon/matchbox/pull/784))
* Refresh docs and examples for Fedora CoreOS and Flatcar Linux ([#815](https://github.com/poseidon/matchbox/pull/815), [#816](https://github.com/poseidon/matchbox/pull/816))
* Update Kubernetes manifest examples ([#791](https://github.com/poseidon/matchbox/pull/791))
* Update base image from `alpine:3.10` to `alpine:3.12` ([#784](https://github.com/poseidon/matchbox/pull/784))
* Include `contrib/k8s` in release tarballs ([#788](https://github.com/poseidon/matchbox/pull/788))
* Remove outdated systemd units ([#817](https://github.com/poseidon/matchbox/pull/817))
* Remove RPM spec file (Copr publishing stopped in v0.6)

## v0.8.3
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -18,7 +18,7 @@

Matchbox can be installed from a binary or a container image.

* Install Matchbox on [Kubernetes](docs/deployment.md#kubernetes), on a [Linux](docs/deployment.md) host, or as a [container](docs/deployment.md#docker)
* Install Matchbox as a [binary](docs/deployment.md#matchbox-binary), as a [container image](docs/deployment.md#container-image), or on [Kubernetes](docs/deployment.md#kubernetes)
* Setup a PXE-enabled [network](docs/network-setup.md)

## Tutorials
Original file line number Diff line number Diff line change
@@ -8,17 +8,19 @@ spec:
rollingUpdate:
maxUnavailable: 1
selector:
matchLabels:
name: matchbox
matchLabels:
name: matchbox
template:
metadata:
labels:
name: matchbox
phase: prod
spec:
securityContext:
seccompProfile:
type: RuntimeDefault
containers:
- name: matchbox
image: quay.io/poseidon/matchbox:v0.8.3
image: quay.io/poseidon/matchbox:v0.9.0
env:
- name: MATCHBOX_ADDRESS
value: "0.0.0.0:8080"
@@ -31,20 +33,25 @@ spec:
containerPort: 8080
- name: https
containerPort: 8081
livenessProbe:
initialDelaySeconds: 5
httpGet:
path: /
port: 8080
resources:
requests:
cpu: "50m"
memory: "50Mi"
cpu: 30m
memory: 20Mi
limits:
cpu: 50m
memory: 50Mi
volumeMounts:
- name: config
mountPath: /etc/matchbox
- name: data
mountPath: /var/lib/matchbox
- name: assets
mountPath: /var/lib/matchbox/assets
dnsPolicy: ClusterFirst
restartPolicy: Always
terminationGracePeriodSeconds: 30
volumes:
- name: config
secret:
19 changes: 15 additions & 4 deletions contrib/k8s/matchbox-ingress.yaml → contrib/k8s/ingress.yaml
Original file line number Diff line number Diff line change
@@ -2,15 +2,22 @@ apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: matchbox
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
ingressClassName: public
# tls ... optional
rules:
- host: matchbox.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
serviceName: matchbox
servicePort: 8080
service:
name: matchbox
port:
number: 8080
---
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
@@ -19,6 +26,7 @@ metadata:
annotations:
nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
ingressClassName: public
tls:
- hosts:
- matchbox-rpc.example.com
@@ -27,6 +35,9 @@ spec:
http:
paths:
- path: /
pathType: Prefix
backend:
serviceName: matchbox
servicePort: 8081
service:
name: matchbox
port:
number: 8081
Original file line number Diff line number Diff line change
@@ -6,7 +6,6 @@ spec:
type: ClusterIP
selector:
name: matchbox
phase: prod
ports:
- name: http
protocol: TCP
16 changes: 0 additions & 16 deletions contrib/systemd/matchbox-local.service

This file was deleted.

22 changes: 0 additions & 22 deletions contrib/systemd/matchbox-on-coreos.service

This file was deleted.

8 changes: 4 additions & 4 deletions contrib/systemd/matchbox.service
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
[Unit]
Description=CoreOS matchbox Server
Documentation=https://github.com/coreos/matchbox
Description=Matchbox Server
Documentation=https://github.com/poseidon/matchbox

[Service]
User=matchbox
Group=matchbox
Environment="MATCHBOX_ADDRESS=0.0.0.0:8080"
ExecStart=/usr/bin/matchbox
ExecStart=/usr/local/bin/matchbox

# systemd.exec
ProtectHome=yes
ProtectSystem=full

[Install]
WantedBy=multi-user.target
WantedBy=multi-user.target
214 changes: 114 additions & 100 deletions docs/deployment.md
Original file line number Diff line number Diff line change
@@ -4,41 +4,43 @@ This guide walks through deploying the `matchbox` service on a Linux host (as a

## Provisoner

`matchbox` is a service for network booting and provisioning machines to create CoreOS Container Linux clusters. `matchbox` should be installed on a provisioner machine (Container Linux or any Linux distribution) or cluster (Kubernetes) which can serve configs to client machines in a lab or datacenter.
Matchbox is a service for network booting and provisioning machines to create Fedora CoreOS or Flatcar Linux clusters. Matchbox may installed on a host server or Kubernetes cluster that can serve configs to client machines in a lab or datacenter.

Choose one of the supported installation options:

* [Generic Linux (binary)](#generic-linux)
* [Kubernetes Service](#kubernetes)
* [With docker](#docker)
* [Matchbox binary](#matchbox-binary)
* [Container image](#container-image)
* [Kubernetes manifests](#kubernetes)

## Download

Download the latest matchbox [release](https://github.com/poseidon/matchbox/releases) to the provisioner host.
Download the latest Matchbox [release](https://github.com/poseidon/matchbox/releases).

```sh
$ wget https://github.com/poseidon/matchbox/releases/download/v0.8.3/matchbox-v0.8.3-linux-amd64.tar.gz
$ wget https://github.com/poseidon/matchbox/releases/download/v0.8.3/matchbox-v0.8.3-linux-amd64.tar.gz.asc
$ wget https://github.com/poseidon/matchbox/releases/download/v0.9.0/matchbox-v0.9.0-linux-amd64.tar.gz
$ wget https://github.com/poseidon/matchbox/releases/download/v0.9.0/matchbox-v0.9.0-linux-amd64.tar.gz.asc
```

Verify the release has been signed by Dalton Hubble's GPG [Key](https://keyserver.ubuntu.com/pks/lookup?search=0x8F515AD1602065C8&op=vindex)'s signing subkey.

```sh
$ gpg --keyserver keyserver.ubuntu.com --recv-key 2E3D92BF07D9DDCCB3BAE4A48F515AD1602065C8
$ gpg --verify matchbox-v0.8.3-linux-amd64.tar.gz.asc matchbox-v0.8.3-linux-amd64.tar.gz
$ gpg --verify matchbox-v0.9.0-linux-amd64.tar.gz.asc matchbox-v0.9.0-linux-amd64.tar.gz
gpg: Good signature from "Dalton Hubble <dghubble@gmail.com>"
```

Untar the release.

```sh
$ tar xzvf matchbox-v0.8.3-linux-amd64.tar.gz
$ cd matchbox-v0.8.3-linux-amd64
$ tar xzvf matchbox-v0.9.0-linux-amd64.tar.gz
$ cd matchbox-v0.9.0-linux-amd64
```

## Install

### Generic Linux
Run Matchbox as a binary, a container image, or on Kubernetes.

### Matchbox Binary

Pre-built binaries are available for generic Linux distributions. Copy the `matchbox` static binary to an appropriate location on the host.

@@ -61,12 +63,12 @@ $ sudo chown -R matchbox:matchbox /var/lib/matchbox
Copy the provided `matchbox` systemd unit file.

```sh
$ sudo cp contrib/systemd/matchbox-local.service /etc/systemd/system/matchbox.service
$ sudo cp contrib/systemd/matchbox.service /etc/systemd/system/matchbox.service
```

## Customization
#### systemd dropins

Customize matchbox by editing the systemd unit or adding a systemd dropin. Find the complete set of `matchbox` flags and environment variables at [config](config.md).
Customize Matchbox by editing the systemd unit or adding a systemd dropin. Find the complete set of `matchbox` flags and environment variables at [config](config.md).

```sh
$ sudo systemctl edit matchbox
@@ -92,6 +94,70 @@ Environment="MATCHBOX_RPC_ADDRESS=0.0.0.0:8081"

Customize `matchbox` to suit your preferences.

#### Start

Start the Matchbox service and enable it if you'd like it to start on every boot.

```
$ sudo systemctl daemon-reload
$ sudo systemctl start matchbox
$ sudo systemctl enable matchbox
```

### Container Image

Run the container image with Podman,

```
mkdir -p /var/lib/matchbox/assets
podman run --net=host --rm -v /var/lib/matchbox:/var/lib/matchbox:Z -v /etc/matchbox:/etc/matchbox:Z,ro quay.io/poseidon/matchbox:v0.9.0 -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
```

Or with Docker,

```
mkdir -p /var/lib/matchbox/assets
sudo docker run --net=host --rm -v /var/lib/matchbox:/var/lib/matchbox:Z -v /etc/matchbox:/etc/matchbox:Z,ro quay.io/poseidon/matchbox:v0.9.0 -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
```

Create machine profiles, groups, or Ignition configs by adding files to `/var/lib/matchbox`.

### Kubernetes

Install Matchbox on a Kubernetes cluster with the example manifests.

```sh
$ kubectl apply -R -f contrib/k8s
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
matchbox 10.3.0.145 <none> 8080/TCP,8081/TCP 46m
```

Example manifests in [contrib/k8s](../contrib/k8s) enable the gRPC API to allow client apps to update matchbox objects. Generate TLS server credentials for `matchbox-rpc.example.com` [as shown](#generate-tls-credentials) and create a Kubernetes secret. Alternately, edit the example manifests if you don't need the gRPC API enabled.

```sh
$ kubectl create secret generic matchbox-rpc --from-file=ca.crt --from-file=server.crt --from-file=server.key
```

Create an Ingress resource to expose the HTTP read-only and gRPC API endpoints. The Ingress example requires the cluster to have a functioning [Nginx Ingress Controller](https://github.com/kubernetes/ingress).

```sh
$ kubectl create -f contrib/k8s/matchbox-ingress.yaml
$ kubectl get ingress
NAME HOSTS ADDRESS PORTS AGE
matchbox matchbox.example.com 10.128.0.3,10... 80 29m
matchbox-rpc matchbox-rpc.example.com 10.128.0.3,10... 80, 443 29m
```

Add DNS records `matchbox.example.com` and `matchbox-rpc.example.com` to route traffic to the Ingress Controller.

Verify `http://matchbox.example.com` responds with the text "matchbox" and verify gRPC clients can connect to `matchbox-rpc.example.com:443`.

```sh
$ curl http://matchbox.example.com
$ openssl s_client -connect matchbox-rpc.example.com:443 -CAfile ca.crt -cert client.crt -key client.key
```

## Firewall

Allow your port choices on the provisioner's firewall so the clients can access the service. Here are the commands for those using `firewalld`:
@@ -141,22 +207,12 @@ $ mkdir -p ~/.matchbox
$ cp client.crt client.key ca.crt ~/.matchbox/
```

## Start matchbox

Start the `matchbox` service and enable it if you'd like it to start on every boot.

```sh
$ sudo systemctl daemon-reload
$ sudo systemctl start matchbox
$ sudo systemctl enable matchbox
```

## Verify

Verify the matchbox service is running and can be reached by client machines (those being provisioned).

```sh
$ systemctl status matchbox
$ systemctl status matchbox # Matchbox binary method
$ dig matchbox.example.com
```

@@ -184,43 +240,47 @@ Certificate chain
....
```

## Download Container Linux (optional)
## Download Images (optional)

`matchbox` can serve Container Linux images in development or lab environments to reduce bandwidth usage and increase the speed of Container Linux PXE boots and installs to disk.
Matchbox can serve OS images in development or lab environments to reduce bandwidth usage and increase the speed of PXE boots and installs to disk.

Download a recent Container Linux [release](https://coreos.com/releases/) with signatures.
Download a recent Fedora CoreOS or Flatcar Linux release.

```sh
$ ./scripts/get-coreos stable 1967.3.0 . # note the "." 3rd argument
```
$ ./scripts/get-fedora-coreos stable 32.20200923.3.0 .
$ ./scripts/get-flatcar stable 2605.6.0 .
```

Move the images to `/var/lib/matchbox/assets`,

```sh
$ sudo cp -r coreos /var/lib/matchbox/assets
```

```
/var/lib/matchbox/assets/
├── coreos
│   └── 1967.3.0
│   ├── CoreOS_Image_Signing_Key.asc
│   ├── coreos_production_image.bin.bz2
│   ├── coreos_production_image.bin.bz2.sig
│   ├── coreos_production_pxe_image.cpio.gz
│   ├── coreos_production_pxe_image.cpio.gz.sig
│   ├── coreos_production_pxe.vmlinuz
│   └── coreos_production_pxe.vmlinuz.sig
/var/lib/matchbox/assets/fedora-coreos/
├── fedora-coreos-32.20200923.3.0-live-initramfs.x86_64.img
├── fedora-coreos-32.20200923.3.0-live-kernel-x86_64
├── fedora-coreos-32.20200923.3.0-live-rootfs.x86_64.img
├── fedora-coreos-32.20200923.3.0-metal.x86_64.raw.xz
└── fedora-coreos-32.20200923.3.0-metal.x86_64.raw.xz.sig
/var/lib/matchbox/assets/flatcar/
└── 2605.6.0
├── Flatcar_Image_Signing_Key.asc
├── flatcar_production_image.bin.bz2
├── flatcar_production_image.bin.bz2.sig
├── flatcar_production_pxe_image.cpio.gz
├── flatcar_production_pxe_image.cpio.gz.sig
├── flatcar_production_pxe.vmlinuz
├── flatcar_production_pxe.vmlinuz.sig
└── version.txt
```

and verify the images are acessible.

```sh
$ curl http://matchbox.example.com:8080/assets/coreos/1967.3.0/
$ curl http://matchbox.example.com:8080/assets/fedora-coreos/
<pre>...
```

For large production environments, use a cache proxy or mirror suitable for your environment to serve Container Linux images.
For large production environments, use a cache proxy or mirror suitable for your environment to serve images.

## Network

@@ -232,63 +292,17 @@ Review [network setup](https://github.com/poseidon/matchbox/blob/master/docs/net

Poseidon provides [dnsmasq](https://github.com/poseidon/matchbox/tree/master/contrib/dnsmasq) as `quay.io/poseidon/dnsmasq`.

## Container Image

Run the container image.

```sh
$ mkdir -p /var/lib/matchbox/assets
$ sudo docker run --net=host --rm -v /var/lib/matchbox:/var/lib/matchbox:Z -v /etc/matchbox:/etc/matchbox:Z,ro quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
```

Create machine profiles, groups, or Ignition configs by adding files to `/var/lib/matchbox`.

## Kubernetes

Install `matchbox` on a Kubernetes cluster by creating a deployment and service.

```sh
$ kubectl apply -f contrib/k8s/matchbox-deployment.yaml
$ kubectl apply -f contrib/k8s/matchbox-service.yaml
$ kubectl get services
NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE
matchbox 10.3.0.145 <none> 8080/TCP,8081/TCP 46m
```

Example manifests in [contrib/k8s](../contrib/k8s) enable the gRPC API to allow client apps to update matchbox objects. Generate TLS server credentials for `matchbox-rpc.example.com` [as shown](#generate-tls-credentials) and create a Kubernetes secret. Alternately, edit the example manifests if you don't need the gRPC API enabled.

```sh
$ kubectl create secret generic matchbox-rpc --from-file=ca.crt --from-file=server.crt --from-file=server.key
```

Create an Ingress resource to expose the HTTP read-only and gRPC API endpoints. The Ingress example requires the cluster to have a functioning [Nginx Ingress Controller](https://github.com/kubernetes/ingress).

```sh
$ kubectl create -f contrib/k8s/matchbox-ingress.yaml
$ kubectl get ingress
NAME HOSTS ADDRESS PORTS AGE
matchbox matchbox.example.com 10.128.0.3,10... 80 29m
matchbox-rpc matchbox-rpc.example.com 10.128.0.3,10... 80, 443 29m
```

Add DNS records `matchbox.example.com` and `matchbox-rpc.example.com` to route traffic to the Ingress Controller.

Verify `http://matchbox.example.com` responds with the text "matchbox" and verify gRPC clients can connect to `matchbox-rpc.example.com:443`.

```sh
$ curl http://matchbox.example.com
$ openssl s_client -connect matchbox-rpc.example.com:443 -CAfile ca.crt -cert client.crt -key client.key
```
# TLS

# HTTPS - The read-only Matchbox API is also available with HTTPS
Matchbox can serve the read-only HTTP API with TLS.

To start matchbox in this mode you will need the following flags set:
| Name | Type | Description |
|----------------|--------|-------------|
| -web-ssl | bool | true/false |
| -web-cert-file | string | Path to the server TLS certificate file |
| -web-key-file | string | Path to the server TLS key file |

| Name | Type | Description |
|----------------|--------|---------------------------------------------------------------|
| -web-ssl | bool | true/false |
| -web-cert-file | string | Path to the server TLS certificate file |
| -web-key-file | string | Path to the server TLS key file |
However, it is more common to use an Ingress Controller (Kubernetes) to terminate TLS.

### Operational notes

4 changes: 2 additions & 2 deletions docs/dev/release.md
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ This guide covers releasing new versions of matchbox.
Create a release commit which updates old version references.

```sh
$ export VERSION=v0.8.3
$ export VERSION=v0.9.0
```

## Tag
@@ -44,7 +44,7 @@ $ make release
Verify the reported version.

```
./_output/matchbox-v0.8.3-linux-amd64/matchbox -version
./_output/matchbox-v0.9.0-linux-amd64/matchbox -version
```

## Signing
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
@@ -12,7 +12,7 @@ Matchbox is a service that matches bare-metal machines to profiles that PXE boot

Matchbox can be installed from a binary or a container image.

* Install Matchbox on [Kubernetes](deployment.md#kubernetes), on a [Linux](deployment.md) host, or as a [container](deployment.md#docker)
* Install Matchbox as a [binary](deployment.md#matchbox-binary), as a [container image](deployment.md#container-image), or on [Kubernetes](deployment.md#kubernetes)
* Setup a PXE-enabled [network](network-setup.md)

## Tutorials
2 changes: 1 addition & 1 deletion docs/matchbox.md
Original file line number Diff line number Diff line change
@@ -172,7 +172,7 @@ matchbox.foo/assets/

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-coreos](https://github.com/poseidon/matchbox/blob/master/scripts/get-coreos) script to quickly download, verify, and place Container Linux assets.
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

14 changes: 0 additions & 14 deletions scripts/dev/get-bootkube

This file was deleted.

13 changes: 0 additions & 13 deletions scripts/dev/get-kubectl

This file was deleted.

5 changes: 2 additions & 3 deletions scripts/dev/release-files
Original file line number Diff line number Diff line change
@@ -18,9 +18,8 @@ cp README.md $DEST

# scripts
mkdir -p $SCRIPTS/tls
cp scripts/get-coreos $SCRIPTS
cp scripts/get-coreos $SCRIPTS
cp scripts/get-coreos $SCRIPTS
cp scripts/get-fedora-coreos $SCRIPTS
cp scripts/get-flatcar $SCRIPTS
cp scripts/tls/README.md $SCRIPTS/tls
cp scripts/tls/cert-gen $SCRIPTS/tls
cp scripts/tls/openssl.conf $SCRIPTS/tls
2 changes: 1 addition & 1 deletion scripts/get-fedora-coreos
Original file line number Diff line number Diff line change
@@ -5,7 +5,7 @@
set -eou pipefail

STREAM=${1:-"stable"}
VERSION=${2:-"31.20200113.3.1"}
VERSION=${2:-"32.20200923.3.0"}
DEST_DIR=${3:-"$PWD/examples/assets"}
DEST=$DEST_DIR/fedora-coreos
BASE_URL=https://builds.coreos.fedoraproject.org/prod/streams/$STREAM/builds/$VERSION/x86_64