github-personal/matchbox
1
0
Fork 0
mirror of https://github.com/outbackdingo/matchbox.git synced 2026-01-27 10:19:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Add guide for installing on CoreOS

Browse Source 
* Provide a systemd service unit which rkt runs bootcfg
This commit is contained in:
Dalton Hubble
2016-08-05 16:09:19 -07:00
parent 05da923fc3
commit 6222fcf802
4 changed files with 145 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

189
Documentation/deployment.md
View File

@@ -5,37 +5,106 @@ This guide walks through deploying the `bootcfg` service on a Linux host (via bi
## Provisoner
`bootcfg` is a service for network booting and provisioning machines to create CoreOS clusters. If the gRPC API is enabled, TLS client-cert authenticated clients (such as `bootcmd` or graphical tools) can be used to programmatically manage machine profiles as well.
`bootcfg` is a service for network booting and provisioning machines to create CoreOS clusters. `bootcfg` should be installed on a provisioner machine (CoreOS or any Linux distribution) or cluster (Kubernetes) which can serve configs to client machines in a lab or datacenter.
`bootcfg` should be deployed to a provisioner node (CoreOS or any Linux distribution) or cluster (Kubernetes) which can serve configurations to client machines in a lab or datacenter. Choose a deployment target and a DNS name (or IP) at which it will be accessed (e.g. bootcfg.example.com).
Choose one of the supported installation options:
## Binary Release
* [CoreOS (systemd & rkt)](#coreos)
* [General Linux (systemd & binary)](#binary-release)
* [With rkt](#rkt)
* [With docker](#docker)
* [Kubernetes Service](#kubernetes)
* RPM package ([coming soon](https://github.com/coreos/coreos-baremetal/issues/266))
## Download
Download the latest coreos-baremetal [release](https://github.com/coreos/coreos-baremetal/releases) to the provisioner host.
wget https://github.com/coreos/coreos-baremetal/releases/download/v0.4.0/coreos-baremetal-v0.4.0-linux-amd64.tar.gz
wget https://github.com/coreos/coreos-baremetal/releases/download/v0.4.0/coreos-baremetal-v0.4.0-linux-amd64.tar.gz.asc
```sh
$ wget https://github.com/coreos/coreos-baremetal/releases/download/v0.4.0/coreos-baremetal-v0.4.0-linux-amd64.tar.gz
$ wget https://github.com/coreos/coreos-baremetal/releases/download/v0.4.0/coreos-baremetal-v0.4.0-linux-amd64.tar.gz.asc
```
Verify the release has been signed by the [CoreOS App Signing Key](https://coreos.com/security/app-signing-key/).
gpg --keyserver pgp.mit.edu --recv-key 18AD5014C99EF7E3BA5F6CE950BDD3E0FC8A365E
gpg --verify coreos-baremetal-v0.4.0-linux-amd64.tar.gz.asc coreos-baremetal-v0.4.0-linux-amd64.tar.gz
# gpg: Good signature from "CoreOS Application Signing Key <security@coreos.com>"
```
$ gpg --keyserver pgp.mit.edu --recv-key 18AD5014C99EF7E3BA5F6CE950BDD3E0FC8A365E
$ gpg --verify coreos-baremetal-v0.4.0-linux-amd64.tar.gz.asc coreos-baremetal-v0.4.0-linux-amd64.tar.gz
# gpg: Good signature from "CoreOS Application Signing Key <security@coreos.com>"
```
Untar the release.
tar xzvf coreos-baremetal-v0.4.0-linux-amd64.tar.gz
cd coreos-baremetal-v0.4.0-linux-amd64
### Copy Binary
Install the `bootcfg` static binary at an appropriate location on the host.
```sh
sudo cp bootcfg /usr/local/bin
$ tar xzvf coreos-baremetal-v0.4.0-linux-amd64.tar.gz
$ cd coreos-baremetal-v0.4.0-linux-amd64
```
### Set Up User/Group
## TLS Credentials
*Skip this unless you need to enable the gRPC API*
The `bootcfg` gRPC API allows external client tools (`bootcmd` CLI, graphical apps) to manage how machines are provisioned so TLS credentials are needed for client authentication and to establish a secure communication channel. Client machines (those PXE booting) read from the HTTP endpoints and do not require this setup.
If your organization manages public key infrastructure and a certificate authority, create a server certificate and key for the `bootcfg` service and a client certificate and key for each client tool.
Otherwise, generate a self-signed `ca.crt`, a server certificate (`server.crt`, `server.key`), and client credentials (`client.crt`, `client.key`) with `scripts/tls/cert-gen`. Export the DNS name or IP (discouraged) of the provisioner host where `bootcfg` will be accessed.
```sh
$ cd scripts/tls
# DNS or IP Subject Alt Names where bootcfg can be reached
$ export SAN=DNS.1:bootcfg.example.com,IP.1:192.168.1.42
$ ./cert-gen
```
Place the TLS credentials in the default location:
```sh
$ sudo mkdir -p /etc/bootcfg
$ sudo cp ca.crt server.crt server.key /etc/bootcfg/
```
Save `client.crt`, `client.key`, and `ca.crt` to use with a client tool later.
## Install
### CoreOS
On CoreOS, it is easiest to run `bootcfg` with the provided systemd unit file.
```sh
$ sudo cp contrib/systemd/bootcfg-on-coreos.service /etc/systemd/system/bootcfg.service
$ sudo systemctl daemon-reload
```
The example systemd unit exposes the `bootcfg` HTTP machine endpoints on port 8080 and the (optional) gRPC API on port 8081 (remove the `-rpc-address` flag if you don't need the gRPC API). Customize the port settings to suit your preferences and be sure to allow your choices within the host's firewall so clients can access the services.
The unit will rkt run the latest tagged `bootcfg` release, signed by the [CoreOS App Signing Key](https://coreos.com/security/app-signing-key/). Trust the public key.
```sh
$ sudo rkt trust --prefix quay.io/coreos/bootcfg
# gpg key fingerprint is: BFF3 13CD AA56 0B16 A898 7B8F 72AB F5F6 799D 33BC
```
Start the `bootcfg` service and enable it if you'd like it to start on every boot.
```sh
$ sudo systemctl enable bootcfg.service
$ sudo systemctl start bootcfg.service
```
### General Linux
Pre-build binaries are available for general Linux distributions. Copy the `bootcfg` static binary to an appropriate location on the host.
#### Binary
```sh
$ sudo cp bootcfg /usr/local/bin
```
#### Set Up User/Group
The `bootcfg` service should be run by a non-root user with access to the `bootcfg` data directory (`/var/lib/bootcfg`). Create a `bootcfg` user and group.
@@ -45,42 +114,18 @@ $ sudo mkdir -p /var/lib/bootcfg/assets
$ sudo chown -R bootcfg:bootcfg /var/lib/bootcfg
```
### Create systemd Service
#### Create systemd Service
Copy the provided `bootcfg` systemd unit file. The example systemd unit exposes the `bootcfg` HTTP machine config endpoints on port 8080 and the (optional) gRPC API on port 8081.
Copy the provided `bootcfg` systemd unit file.
```sh
sudo cp contrib/systemd/bootcfg.service /etc/systemd/system/
sudo systemctl daemon-reload
$ sudo cp contrib/systemd/bootcfg.service /etc/systemd/system/
$ sudo systemctl daemon-reload
```
Customize the port settings to suit your preferences and be sure to allow your choices within the host's firewall so client machines can access the services. The gRPC API can be disabled by removing the `-rpc-address` flag if you don't need higher level tools (CLI, graphical tools) for managing machine profiles and you may skip the next section.
The example systemd unit exposes the `bootcfg` HTTP machine endpoints on port 8080 and the (optional) gRPC API on port 8081 (remove the `-rpc-address` flag if you don't need the gRPC API). Customize the port settings to suit your preferences and be sure to allow your choices within the host's firewall so clients can access the services.
### TLS Credentials
*Skip unless gRPC API enabled (optional)*
`bootcfg` provisions machines so, if the gRPC API is enabled, it is important for client-server communications to be TLS encrypted and for clients to authenticate with client certificates. If your organization manages public key infrastructure and a certificate authority, create a server certificate and key for the `bootcfg` service and a client certificate and key for each client tool.
Otherwise, you can generate a self-signed `ca.crt`, a server certificate (`server.crt`, `server.key`), and client credentials (`client.crt`, `client.key`) with `scripts/tls/cert-gen`. Export the DNS name (or IP) of the provisioner host where `bootcfg` will be accessed.
```sh
$ cd scripts/tls
$ export SAN=DNS.1:bootcfg.example.com,IP.1:192.168.1.100
$ ./cert-gen
```
Place the TLS credentials in the default locations:
```sh
$ sudo mkdir /etc/bootcfg
$ sudo cp ca.crt server.crt server.key /etc/bootcfg/
```
Save `client.crt`, `client.key`, and `ca.crt` to use with a client tool later.
### Start bootcfg
#### Start bootcfg
Start the `bootcfg` service and enable it if you'd like it to start on every boot.
@@ -89,9 +134,9 @@ $ sudo systemctl enable bootcfg.service
$ sudo systemctl start bootcfg.service
```
### Verify
## Verify
Check the bootcfg service can be reached by client machines.
Check the bootcfg service can be reached by client machines (those being provisioned).
```sh
@@ -108,7 +153,7 @@ bootcfg
If you enabled the gRPC API,
```sh
$ openssl s_client -connect bootcfg.example.com:8081 -CAfile /etc/bootcfg/ca.crt -cert client.key -key client.key
$ openssl s_client -connect bootcfg.example.com:8081 -CAfile /etc/bootcfg/ca.crt -cert client.crt -key client.key
CONNECTED(00000003)
depth=1 CN = fake-ca
verify return:1
@@ -122,7 +167,7 @@ Certificate chain
....
```
### Download CoreOS (optional)
## Download CoreOS (optional)
`bootcfg` can serve CoreOS image assets in development or lab environments to reduce bandwidth usage and increase the speed of CoreOS PXE boots and installs to disk.
@@ -159,9 +204,7 @@ $ curl http://bootcfg.example.com:8080/assets/coreos/1109.1.0/
For large production environments, use a cache proxy or mirror suitable for your environment to serve CoreOS images.
## Next Steps
### Network
## Network
Review [network setup](https://github.com/coreos/coreos-baremetal/blob/master/Documentation/network-setup.md) with your network administrator to set up DHCP, TFTP, and DNS services on your network, if it has not already been done. At a high level, your goals are to:
@@ -171,17 +214,15 @@ Review [network setup](https://github.com/coreos/coreos-baremetal/blob/master/Do
CoreOS provides [dnsmasq](https://github.com/coreos/coreos-baremetal/tree/master/contrib/dnsmasq) as `quay.io/coreos/dnsmasq`, if you wish to use rkt or Docker.
### Documentation
View the [documentation](https://github.com/coreos/coreos-baremetal#coreos-on-baremetal) for `bootcfg` service docs, tutorials, example clusters and Ignition configs, PXE booting guides, or machine lifecycle guides.
## rkt
Run the most recent tagged and signed `bootcfg` [release](https://github.com/coreos/coreos-baremetal/releases) ACI. Trust the [CoreOS App Signing Key](https://coreos.com/security/app-signing-key/) for image signature verification.
sudo rkt trust --prefix coreos.com/bootcfg
# gpg key fingerprint is: 18AD 5014 C99E F7E3 BA5F 6CE9 50BD D3E0 FC8A 365E
sudo rkt run --net=host --mount volume=assets,target=/var/lib/bootcfg/assets --volume assets,kind=host,source=$PWD/examples/assets quay.io/coreos/bootcfg:v0.4.0 -- -address=0.0.0.0:8080 -log-level=debug
```sh
$ sudo rkt trust --prefix coreos.com/bootcfg
# gpg key fingerprint is: 18AD 5014 C99E F7E3 BA5F 6CE9 50BD D3E0 FC8A 365E
$ sudo rkt run --net=host --mount volume=data,target=/var/lib/bootcfg --volume data,kind=host,source=/var/lib/bootcfg quay.io/coreos/bootcfg:v0.4.0 --mount volume=config,target=/etc/bootcfg --volume config,kind=host,source=/etc/bootcfg,readOnly=true -- -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
```
Create machine profiles, groups, or Ignition configs at runtime with `bootcmd` or by using your own `/var/lib/bootcfg` volume mounts.
@@ -189,24 +230,34 @@ Create machine profiles, groups, or Ignition configs at runtime with `bootcmd` o
Run the latest or the most recently tagged `bootcfg` [release](https://github.com/coreos/coreos-baremetal/releases) Docker image.
sudo docker run --net=host --rm -v $PWD/examples/assets:/var/lib/bootcfg/assets:Z quay.io/coreos/bootcfg:v0.4.0 -address=0.0.0.0:8080 -log-level=debug
```sh
sudo docker run --net=host --rm -v /var/lib/bootcfg:/var/lib/bootcfg:Z -v /etc/bootcfg:/etc/bootcfg:Z,ro quay.io/coreos/bootcfg:v0.4.0 -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
```
Create machine profiles, groups, or Ignition configs at runtime with `bootcmd` or by using your own `/var/lib/bootcfg` volume mounts.
## Kubernetes
*Note: Enhancements to the CLI, and `EtcdStore` backend will improve this deployment strategy in the future.*
*Note: Enhancements to the CLI and `EtcdStore` backend will improve this deployment strategy in the future.*
Create a `bootcfg` Kubernetes `Deployment` and `Service` based on the example manifests provided in [contrib/k8s](../contrib/k8s).
kubectl apply -f contrib/k8s/bootcfg-deployment.yaml
kubectl apply -f contrib/k8s/bootcfg-service.yaml
```
$ kubectl apply -f contrib/k8s/bootcfg-deployment.yaml
$ kubectl apply -f contrib/k8s/bootcfg-service.yaml
```
The `bootcfg` HTTP server should be exposed on NodePort `tcp:31488` on each node in the cluster. `BOOTCFG_LOG_LEVEL` is set to debug.
kubectl get deployments
kubectl get services
kubectl get pods
kubectl logs POD-NAME
```sh
$ kubectl get deployments
$ kubectl get services
$ kubectl get pods
$ kubectl logs POD-NAME
```
The example manifests use Kubernetes `emptyDir` volumes to back the `bootcfg` FileStore (`/var/lib/bootcfg`). This doesn't provide long-term persistent storage so you may wish to mount your machine groups, profiles, and Ignition configs with a [gitRepo](http://kubernetes.io/docs/user-guide/volumes/#gitrepo) and host image assets on a file server.
### Documentation
View the [documentation](https://github.com/coreos/coreos-baremetal#coreos-on-baremetal) for `bootcfg` service docs, tutorials, example clusters and Ignition configs, PXE booting guides, or machine lifecycle guides.

2
README.md
View File

@@ -30,7 +30,7 @@ Guides and a service for network booting and provisioning CoreOS clusters on vir
* Backends
* [FileStore](Documentation/bootcfg.md#data)
* Installation
* [Binary](Documentation/deployment.md#binary-release)
* [CoreOS / Linux distros](Documentation/deployment.md)
* [rkt](Documentation/deployment.md#rkt) / [docker](Documentation/deployment.md#docker)
* [Kubernetes](Documentation/deployment.md#kubernetes)
* [Troubleshooting](Documentation/troubleshooting.md)

22
contrib/systemd/bootcfg-on-coreos.service Normal file
View File

@@ -0,0 +1,22 @@
[Unit]
Description=CoreOS bootcfg Server
Documentation=https://github.com/coreos/coreos-baremetal
[Service]
ExecStartPre=/usr/bin/mkdir -p /var/lib/bootcfg/assets
ExecStart=/usr/bin/rkt run \
--net=host \
--mount volume=data,target=/var/lib/bootcfg \
--mount volume=config,target=/etc/bootcfg \
--volume data,kind=host,source=/var/lib/bootcfg \
--volume config,kind=host,source=/etc/bootcfg \
quay.io/coreos/bootcfg:v0.4.0 -- -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
# systemd.exec
ProtectHome=yes
ProtectSystem=full
ReadOnlyPaths=/etc/bootcfg
ReadWritePaths=/var/lib/bootcfg
[Install]
WantedBy=multi-user.target

4
contrib/systemd/bootcfg.service
View File

@@ -3,7 +3,6 @@ Description=CoreOS bootcfg Server
Documentation=https://github.com/coreos/coreos-baremetal
[Service]
Type=simple
User=bootcfg
Group=bootcfg
ExecStart=/usr/local/bin/bootcfg -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081 -log-level=debug
@@ -11,7 +10,8 @@ ExecStart=/usr/local/bin/bootcfg -address=0.0.0.0:8080 -rpc-address=0.0.0.0:8081
# systemd.exec
ProtectHome=yes
ProtectSystem=full
ReadWriteDirectories=/var/lib/bootcfg
ReadOnlyPaths=/etc/bootcfg
ReadWritePaths=/var/lib/bootcfg
[Install]
WantedBy=multi-user.target