Merge pull request #452 from radhikapc/master

Documentation/*.md: Make headings sentence case

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).
 

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:
 

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.

Documentation/cloud-config.md

@@ -1,5 +1,5 @@
 
-# Cloud Config
+# Cloud config
 
 **Note:** We recommend migrating to [Ignition](ignition.md) for hardware provisioning.
 

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.
 

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.

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`.
 

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.
 

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`.

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`.
-

Documentation/grub.md

@@ -1,5 +1,5 @@
 
-# GRUB2 Netboot
+# GRUB2 netboot
 
 Use GRUB to network boot UEFI hardware.
 

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.
 

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)
-
-
-

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)

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.
 

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.
 

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).
 

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).
 

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.