From 08504aabc537a9ed0547c619152240067a196db5 Mon Sep 17 00:00:00 2001 From: Radhika Puthiyetath Date: Tue, 7 Mar 2017 16:10:51 -0800 Subject: [PATCH] Documentation/*.md: Make headings sentence case. Performed the following checks: sentence case index heading 2 matchbox - proper noun and capitalized --- Documentation/api.md | 16 ++++++++-------- Documentation/bootkube-upgrades.md | 6 +++--- Documentation/bootkube.md | 6 +++--- Documentation/cloud-config.md | 2 +- Documentation/config.md | 14 +++++++------- Documentation/deployment.md | 10 +++++----- Documentation/dev/develop.md | 4 ++-- Documentation/dev/release.md | 4 ++-- Documentation/getting-started-docker.md | 6 +++--- Documentation/getting-started-rkt.md | 7 +++---- Documentation/grub.md | 2 +- Documentation/ignition.md | 4 ++-- Documentation/machine-lifecycle.md | 9 +++++---- Documentation/matchbox.md | 8 ++++---- Documentation/network-booting.md | 4 ++-- Documentation/network-setup.md | 2 +- Documentation/openpgp.md | 4 ++-- Documentation/rktnetes.md | 2 +- Documentation/troubleshooting.md | 2 +- 19 files changed, 56 insertions(+), 56 deletions(-) diff --git a/Documentation/api.md b/Documentation/api.md index 0272de81..2a8e97a4 100644 --- a/Documentation/api.md +++ b/Documentation/api.md @@ -1,7 +1,7 @@ # HTTP API -## iPXE Script +## iPXE script Serves a static iPXE boot script which gathers client machine attributes and chainloads to the iPXE endpoint. Use DHCP/TFTP to point iPXE clients to this endpoint as the next-server. @@ -27,7 +27,7 @@ Finds the profile for the machine and renders the network boot config (kernel, o GET http://matchbox.foo/ipxe?label=value ``` -**Query Parameters** +**Query parameters** | Name | Type | Description | |------|--------|-----------------| @@ -52,7 +52,7 @@ Finds the profile for the machine and renders the network boot config as a GRUB GET http://matchbox.foo/grub?label=value ``` -**Query Parameters** +**Query parameters** | Name | Type | Description | |------|--------|-----------------| @@ -73,7 +73,7 @@ initrdefi "(http;matchbox.foo:8080)/assets/coreos/1235.9.0/coreos_production_pxe } ``` -## Cloud Config +## Cloud config Finds the profile matching the machine and renders the corresponding Cloud-Config with group metadata, selectors, and query params. @@ -109,7 +109,7 @@ Finds the profile matching the machine and renders the corresponding Ignition Co GET http://matchbox.foo/ignition?label=value ``` -**Query Parameters** +**Query parameters** | Name | Type | Description | |------|--------|-----------------| @@ -132,7 +132,7 @@ GET http://matchbox.foo/ignition?label=value } ``` -## Generic Config +## Generic config Finds the profile matching the machine and renders the corresponding generic config with group metadata, selectors, and query params. @@ -140,7 +140,7 @@ Finds the profile matching the machine and renders the corresponding generic con GET http://matchbox.foo/generic?label=value ``` -**Query Parameters** +**Query parameters** | Name | Type | Description | |------|--------|-----------------| @@ -189,7 +189,7 @@ REQUEST_QUERY_GATE=true REQUEST_RAW_QUERY=mac=52-54-00-a1-9c-ae&foo=bar&count=3&gate=true ``` -## OpenPGP Signatures +## OpenPGP signatures OpenPGPG signature endpoints serve detached binary and ASCII armored signatures of rendered configs, if enabled. See [OpenPGP Signing](openpgp.md). diff --git a/Documentation/bootkube-upgrades.md b/Documentation/bootkube-upgrades.md index f7495b3a..87f1c47f 100644 --- a/Documentation/bootkube-upgrades.md +++ b/Documentation/bootkube-upgrades.md @@ -1,5 +1,5 @@ -# Upgrading Self-hosted Kubernetes +# Upgrading self-hosted Kubernetes [Self-hosted](bootkube.md) Kubernetes clusters schedule Kubernetes components such as the apiserver, kubelet, scheduler, and controller-manager as pods like other applications (except with node selectors). This allows Kubernetes level operations to be performed to upgrade clusters in place, rather than by re-provisioning. @@ -119,7 +119,7 @@ Server Version: version.Info{Major:"1", Minor:"4", GitVersion:"v1.4.3+coreos.0", Finally, upgrade the kubelets and kube-proxies. -## Kubelet and Proxy +## kubelet and kube-proxy Show the current kubelet and kube-proxy version on each node. @@ -180,7 +180,7 @@ $ kubectl get nodes -o yaml | grep 'kubeletVersion\|kubeProxyVersion' Now, Kubernetes components have been upgraded to a new version of Kubernetes! -## Going Further +## Going further Bare-metal or virtualized self-hosted Kubernetes clusters can be upgraded in place in 5-10 minutes. Here is a bare-metal example: diff --git a/Documentation/bootkube.md b/Documentation/bootkube.md index 84f880e2..7081fa3a 100644 --- a/Documentation/bootkube.md +++ b/Documentation/bootkube.md @@ -1,5 +1,5 @@ -# Self-Hosted Kubernetes +# Self-hosted Kubernetes The self-hosted Kubernetes example provisions a 3 node "self-hosted" Kubernetes v1.5.3 cluster. On-host kubelets wait for an apiserver to become reachable, then yield to kubelet pods scheduled via daemonset. [bootkube](https://github.com/kubernetes-incubator/bootkube) is run on any controller to bootstrap a temporary apiserver which schedules control plane components as pods before exiting. An etcd cluster backs Kubernetes and coordinates CoreOS auto-updates (enabled for disk installs). @@ -28,7 +28,7 @@ The [examples](../examples) statically assign IP addresses to libvirt client VMs * [bootkube](../examples/groups/bootkube) - iPXE boot a self-hosted Kubernetes cluster * [bootkube-install](../examples/groups/bootkube-install) - Install a self-hosted Kubernetes cluster -### Assets +## Assets Download the CoreOS image assets referenced in the target [profile](../examples/profiles). @@ -124,6 +124,6 @@ kube-system pod-checkpointer-node1.example.com 1/1 Running 2 Try deleting pods to see that the cluster is resilient to failures and machine restarts (CoreOS auto-updates). -## Going Further +## Going further [Learn](bootkube-upgrades.md) to upgrade a self-hosted Kubernetes cluster. diff --git a/Documentation/cloud-config.md b/Documentation/cloud-config.md index 6820056a..b308433f 100644 --- a/Documentation/cloud-config.md +++ b/Documentation/cloud-config.md @@ -1,5 +1,5 @@ -# Cloud Config +# Cloud config **Note:** We recommend migrating to [Ignition](ignition.md) for hardware provisioning. diff --git a/Documentation/config.md b/Documentation/config.md index a9dbc721..b8a8de5c 100644 --- a/Documentation/config.md +++ b/Documentation/config.md @@ -1,5 +1,5 @@ -# Flags and Variables +# Flags and variables Configuration arguments can be provided as flags or as environment variables. @@ -16,7 +16,7 @@ Configuration arguments can be provided as flags or as environment variables. | -key-ring-path | MATCHBOX_KEY_RING_PATH | (no key ring) | ~/.secrets/vault/matchbox/secring.gpg | | (no flag) | MATCHBOX_PASSPHRASE | (no passphrase) | "secret passphrase" | -## Files and Directories +## Files and directories | Data | Default Location | |:---------|:--------------------------------------------------| @@ -59,7 +59,7 @@ Run the latest Docker image. $ sudo docker run -p 8080:8080 --rm -v $PWD/examples/assets:/var/lib/matchbox/assets:Z quay.io/coreos/matchbox:latest -address=0.0.0.0:8080 -log-level=debug ``` -#### With Examples +### With examples Mount `examples` to pre-load the [example](../examples/README.md) machine groups and profiles. Run the container with rkt, @@ -73,7 +73,7 @@ or with Docker. $ sudo docker run -p 8080:8080 --rm -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/groups/etcd:/var/lib/matchbox/groups:Z quay.io/coreos/matchbox:latest -address=0.0.0.0:8080 -log-level=debug ``` -### gRPC API +### With gRPC API The gRPC API allows clients with a TLS client certificate and key to make RPC requests to programmatically create or update `matchbox` resources. The API can be enabled with the `-rpc-address` flag and by providing a TLS server certificate and key with `-cert-file` and `-key-file` and a CA certificate for authenticating clients with `-ca-file`. @@ -89,7 +89,7 @@ Clients, such as `bootcmd`, verify the server's certificate with a CA bundle pas $ ./bin/bootcmd profile list --endpoints 127.0.0.1:8081 --ca-file examples/etc/matchbox/ca.crt --cert-file examples/etc/matchbox/client.crt --key-file examples/etc/matchbox/client.key ``` -#### With rkt +### With rkt Run the ACI with rkt and TLS credentials from `examples/etc/matchbox`. @@ -103,7 +103,7 @@ A `bootcmd` client can call the gRPC API running at the IP used in the rkt examp $ ./bin/bootcmd profile list --endpoints 172.18.0.2:8081 --ca-file examples/etc/matchbox/ca.crt --cert-file examples/etc/matchbox/client.crt --key-file examples/etc/matchbox/client.key ``` -#### With docker +### With docker Run the Docker image with TLS credentials from `examples/etc/matchbox`. @@ -117,7 +117,7 @@ A `bootcmd` client can call the gRPC API running at the IP used in the Docker ex $ ./bin/bootcmd profile list --endpoints 127.0.0.1:8081 --ca-file examples/etc/matchbox/ca.crt --cert-file examples/etc/matchbox/client.crt --key-file examples/etc/matchbox/client.key ``` -### OpenPGP [Signing](openpgp.md) +### With openPGP [Signing](openpgp.md) Run with the binary with a test key. diff --git a/Documentation/deployment.md b/Documentation/deployment.md index b0e3fea6..05cfa73f 100644 --- a/Documentation/deployment.md +++ b/Documentation/deployment.md @@ -42,7 +42,7 @@ $ cd matchbox-v0.5.0-linux-amd64 ## Install -### RPM-based Distro +### RPM-based distro On an RPM-based provisioner, install the `matchbox` RPM from the Copr [repository](https://copr.fedorainfracloud.org/coprs/g/CoreOS/matchbox/) using `dnf` or `yum`. @@ -67,7 +67,7 @@ Pre-built binaries are available for generic Linux distributions. Copy the `matc $ sudo cp matchbox /usr/local/bin ``` -#### Set Up User/Group +#### Set up User/Group The `matchbox` service should be run by a non-root user with access to the `matchbox` data directory (`/var/lib/matchbox`). Create a `matchbox` user and group. @@ -77,7 +77,7 @@ $ sudo mkdir -p /var/lib/matchbox/assets $ sudo chown -R matchbox:matchbox /var/lib/matchbox ``` -#### Create systemd Service +#### Create systemd service Copy the provided `matchbox` systemd unit file. @@ -128,7 +128,7 @@ $ sudo firewall-cmd --zone=MYZONE --add-port=8080/tcp --permanent $ sudo firewall-cmd --zone=MYZONE --add-port=8081/tcp --permanent ``` -## Generate TLS Credentials +## Generate TLS credentials *Skip this unless you need to enable the gRPC API* @@ -287,6 +287,6 @@ $ kubectl logs POD-NAME The example manifests use Kubernetes `emptyDir` volumes to back the `matchbox` FileStore (`/var/lib/matchbox`). 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 +## Documentation View the [documentation](https://github.com/coreos/matchbox#coreos-on-baremetal) for `matchbox` service docs, tutorials, example clusters and Ignition configs, PXE booting guides, or machine lifecycle guides. diff --git a/Documentation/dev/develop.md b/Documentation/dev/develop.md index ff09345f..074e90fc 100644 --- a/Documentation/dev/develop.md +++ b/Documentation/dev/develop.md @@ -2,7 +2,7 @@ To develop `matchbox` locally, compile the binary and build the container image. -## Static Binary +## Static binary Build the static binary. @@ -16,7 +16,7 @@ Test with vendored dependencies. $ make test ``` -## Container Image +## Container image Build an ACI `matchbox.aci`. diff --git a/Documentation/dev/release.md b/Documentation/dev/release.md index 96b07219..40fa84da 100644 --- a/Documentation/dev/release.md +++ b/Documentation/dev/release.md @@ -1,5 +1,5 @@ -# Release Guide +# Release guide This guide covers releasing new versions of matchbox. @@ -30,7 +30,7 @@ $ sudo docker run quay.io/coreos/matchbox:$VERSION -version $ sudo rkt run --no-store quay.io/coreos/matchbox:$VERSION -- -version ``` -## Github Release +## Github release Publish the release on Github with release notes. diff --git a/Documentation/getting-started-docker.md b/Documentation/getting-started-docker.md index 94418fcc..986116fc 100644 --- a/Documentation/getting-started-docker.md +++ b/Documentation/getting-started-docker.md @@ -1,5 +1,5 @@ -# Getting Started with Docker +# Getting started with Docker In this tutorial, we'll run `matchbox` on your Linux machine with Docker to network boot and provision a cluster of QEMU/KVM CoreOS machines locally. You'll be able to create Kubernetes clusters, etcd3 clusters, and test network setups. @@ -105,7 +105,7 @@ $ ETCDCTL_API=3 $ etcdctl set /message hello $ etcdctl get /message ``` -## Cleanup +## Clean up Clean up the containers and VM machines. @@ -115,6 +115,6 @@ $ sudo ./scripts/libvirt poweroff $ sudo ./scripts/libvirt destroy ``` -## Going Further +## Going further Learn more about [matchbox](matchbox.md) or explore the other [example](../examples) clusters. Try the [k8s example](kubernetes.md) to produce a TLS-authenticated Kubernetes cluster you can access locally with `kubectl`. diff --git a/Documentation/getting-started-rkt.md b/Documentation/getting-started-rkt.md index 6fd0abbf..1624f6d4 100644 --- a/Documentation/getting-started-rkt.md +++ b/Documentation/getting-started-rkt.md @@ -1,4 +1,4 @@ -# Getting Started with rkt +# Getting started with rkt In this tutorial, we'll run `matchbox` on your Linux machine with `rkt` and `CNI` to network boot and provision a cluster of QEMU/KVM CoreOS machines locally. You'll be able to create Kubernetes clustes, etcd3 clusters, and test network setups. @@ -163,7 +163,7 @@ $ etcdctl set /message hello $ etcdctl get /message ``` -## Cleanup +## Clean up Clean up the systemd units running `matchbox` and `dnsmasq`. @@ -179,7 +179,6 @@ $ sudo ./scripts/libvirt destroy Press ^] three times to stop any rkt pod. -## Going Further +## Going further Learn more about [matchbox](matchbox.md) or explore the other [example](../examples) clusters. Try the [k8s example](kubernetes.md) to produce a TLS-authenticated Kubernetes cluster you can access locally with `kubectl`. - diff --git a/Documentation/grub.md b/Documentation/grub.md index ad7da8c9..968b55cb 100644 --- a/Documentation/grub.md +++ b/Documentation/grub.md @@ -1,5 +1,5 @@ -# GRUB2 Netboot +# GRUB2 netboot Use GRUB to network boot UEFI hardware. diff --git a/Documentation/ignition.md b/Documentation/ignition.md index f4e2924b..f4729957 100644 --- a/Documentation/ignition.md +++ b/Documentation/ignition.md @@ -2,13 +2,13 @@ Ignition is a system for declaratively provisioning disks during the initramfs, before systemd starts. It runs only on the first boot and handles partitioning disks, formatting partitions, writing files (regular files, systemd units, networkd units, etc.), and configuring users. See the Ignition [docs](https://coreos.com/ignition/docs/latest/) for details. -## Fuze Configs +## Fuze configs Ignition 2.0.0+ configs are versioned, *machine-friendly* JSON documents (which contain encoded file contents). Operators should write and maintain configs in a *human-friendly* format, such as CoreOS [fuze](https://github.com/coreos/fuze) configs. As of `matchbox` v0.4.0, Fuze configs are the primary way to use CoreOS Ignition. The [Fuze schema](https://github.com/coreos/fuze/blob/master/doc/configuration.md) formalizes and improves upon the YAML to Ignition JSON transform. Fuze provides better support for Ignition 2.0.0+, handles file content encoding, patches Ignition bugs, performs better validations, and lets services (like `matchbox`) negotiate the Ignition version required by a CoreOS client. -## Adding Fuze Configs +### Adding Fuze configs Fuze template files can be added in 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. diff --git a/Documentation/machine-lifecycle.md b/Documentation/machine-lifecycle.md index b391f921..d2239892 100644 --- a/Documentation/machine-lifecycle.md +++ b/Documentation/machine-lifecycle.md @@ -1,4 +1,6 @@ -# Lifecycle of a Physical Machine +# Lifecycle of a physical machine + +## About boot environment Physical machines [network boot](network-booting.md) in an network boot environment with DHCP/TFTP/DNS services or with [coreos/dnsmasq](../contrib/dnsmasq). @@ -8,7 +10,6 @@ CoreOS boots ("first boot" from disk) and runs Ignition to provision its disk wi Coordinated auto-updates are enabled. Systems like [fleet](https://coreos.com/docs/#fleet) or [Kubernetes](http://kubernetes.io/docs/) coordinate container services. IPMI, vendor utilities, or first-boot are used to re-provision machines into new roles. +## Machine lifecycle + ![Machine Lifecycle](img/machine-lifecycle.png) - - - diff --git a/Documentation/matchbox.md b/Documentation/matchbox.md index 82d87cd0..fa4db9f3 100644 --- a/Documentation/matchbox.md +++ b/Documentation/matchbox.md @@ -7,7 +7,7 @@ Network boot endpoints provide PXE, iPXE, GRUB support. `matchbox` can be deploy ![Bootcfg Overview](img/overview.png) -## Getting Started +## Getting started Get started running `matchbox` on your Linux machine, with rkt or Docker. @@ -119,7 +119,7 @@ Meanwhile, `/var/lib/matchbox/groups/proxy.json` acts as the default machine gro 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 +#### 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. @@ -128,7 +128,7 @@ Group selectors can use any key/value pairs you find useful. However, several la * `hostname` - hostname reported by a network boot program * `serial` - serial reported by a network boot program -### Config Templates +### Config templates Profiles can reference various templated configs. Ignition JSON configs can be generated from [Fuze config](https://github.com/coreos/fuze/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. @@ -180,7 +180,7 @@ See the [get-coreos](../scripts/README.md#get-coreos) script to quickly download `matchbox` does not implement or exec a DHCP/TFTP server. Read [network setup](network-setup.md) or use the [coreos/dnsmasq](../contrib/dnsmasq) image if you need a quick DHCP, proxyDHCP, TFTP, or DNS setup. -## Going Further +## Going further * [gRPC API Usage](config.md#grpc-api) * [Metadata](api.md#metadata) diff --git a/Documentation/network-booting.md b/Documentation/network-booting.md index 6f67d833..7e39eaeb 100644 --- a/Documentation/network-booting.md +++ b/Documentation/network-booting.md @@ -1,5 +1,5 @@ -# Network Boot Environments +# Network boot environments This guide reviews network boot protocols and the different ways client machines can be PXE booted. @@ -13,7 +13,7 @@ At power-on, if a client machine's BIOS or UEFI boot firmware is set to perform The network environment can be set up in a number of ways, which we'll discuss. In the simplest, a PXE-enabled DHCP Server responds with a DHCPOFFER with Options, which include a TFTP server IP ("next server") and the name of an NBP ("boot filename") to download (e.g. pxelinux.0). PXE firmware then downloads the NBP over TFTP and starts it. Finally, the NBP loads configs, scripts, and/or images it requires to run an OS. -### Network Boot Programs +### Network boot programs Machines can be booted and configured with CoreOS using several network boot programs and approaches. Let's review them. If you're new to network booting or unsure which to choose, iPXE is a reasonable and flexible choice. diff --git a/Documentation/network-setup.md b/Documentation/network-setup.md index 9b529066..6762b4ea 100644 --- a/Documentation/network-setup.md +++ b/Documentation/network-setup.md @@ -1,4 +1,4 @@ -# Network Setup +# Network setup This guide shows how to create a DHCP/TFTP/DNS network boot environment to work with `matchbox` to boot and provision PXE, iPXE, or GRUB2 client machines. diff --git a/Documentation/openpgp.md b/Documentation/openpgp.md index 74757901..d178871a 100644 --- a/Documentation/openpgp.md +++ b/Documentation/openpgp.md @@ -1,5 +1,5 @@ -# OpenPGP Signing +# OpenPGP signing The `matchbox` OpenPGP signature endpoints serve detached binary and ASCII armored signatures of rendered configs, if enabled. Each config endpoint has corresponding signature endpoints, typically suffixed with `.sig` or `.asc`. @@ -35,7 +35,7 @@ gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: BE2F 12BC 3642 2594 570A CCBB 8DC4 2020 9896 356A ``` -## Signing Key Generation +## Signing key generation Create a signing key or subkey according to your requirements and security policies. Here are some basic [guides](https://coreos.com/rkt/docs/latest/signing-and-verification-guide.html). diff --git a/Documentation/rktnetes.md b/Documentation/rktnetes.md index 68c7959a..e471424a 100644 --- a/Documentation/rktnetes.md +++ b/Documentation/rktnetes.md @@ -19,7 +19,7 @@ The [examples](../examples) statically assign IP addresses to libvirt client VMs * [rktnetes-install](../examples/groups/rktnetes-install) - Install a Kubernetes cluster to disk * [Lab examples](https://github.com/dghubble/metal) - Lab hardware examples -### Assets +## Assets Download the CoreOS image assets referenced in the target [profile](../examples/profiles). diff --git a/Documentation/troubleshooting.md b/Documentation/troubleshooting.md index 54429b72..c4187c98 100644 --- a/Documentation/troubleshooting.md +++ b/Documentation/troubleshooting.md @@ -4,7 +4,7 @@ Running DHCP or proxyDHCP with `coreos/dnsmasq` on a host requires that the Firewall allow DHCP and TFTP (for chainloading) services to run. -## Port Collision +## Port collision Running DHCP or proxyDHCP can cause port already in use collisions depending on what's running. Fedora runs bootp listening on udp/67 for example. Find the service using the port.