chore: enforce one sentence per line in Markdown files

This is widely considered best practice, we should enforce it.

Signed-off-by: Andrew Rynhard <andrew@andrewrynhard.com>

Dockerfile

@@ -301,7 +301,8 @@ RUN --mount=type=cache,target=/.cache/go-build golangci-lint run --config golang
 
 FROM node:8.16.1-alpine AS markdownlint
 RUN npm install -g markdownlint-cli
+RUN npm i sentences-per-line
 WORKDIR /src
 COPY .markdownlint.json .
 COPY docs .
-RUN markdownlint .
+RUN markdownlint --rules /node_modules/sentences-per-line/index.js .

docs/content/components/init.md

@@ -9,9 +9,14 @@ menu:
     weight: 20
 ---
 
-A common theme throughout the design of Talos is minimalism. We believe strongly in the UNIX philosophy that each program should do one job well. The `init` included in Talos is one example of this.
+A common theme throughout the design of Talos is minimalism.
+We believe strongly in the UNIX philosophy that each program should do one job well.
+The `init` included in Talos is one example of this.
 
-We wanted to create a focused `init` that had one job - run Kubernetes. To that extent, `init` is relatively static in that it does not allow for arbitrary user defined services. Only the services necessary to run Kubernetes and manage the node are available. This includes:
+We wanted to create a focused `init` that had one job - run Kubernetes.
+To that extent, `init` is relatively static in that it does not allow for arbitrary user defined services.
+Only the services necessary to run Kubernetes and manage the node are available.
+This includes:
 
 - [containerd](/docs/components/containerd)
 - [kubeadm](/docs/components/kubeadm)

docs/content/components/kubeadm.md

@@ -7,6 +7,8 @@ menu:
     parent: 'components'
 ---
 
-[`kubeadm`](https://github.com/kubernetes/kubernetes/tree/master/cmd/kubeadm) handles the installation and configuration of Kubernetes. This is done to stay as close as possible to upstream Kubernetes best practices and recommendations. By integrating with `kubeadm` natively, the development and operational ecosystem is familiar to all Kubernetes users.
+[`kubeadm`](https://github.com/kubernetes/kubernetes/tree/master/cmd/kubeadm) handles the installation and configuration of Kubernetes.
+This is done to stay as close as possible to upstream Kubernetes best practices and recommendations.
+By integrating with `kubeadm` natively, the development and operational ecosystem is familiar to all Kubernetes users.
 
 Kubeadm configuration is defined in the userdata under the `services.kubeadm` section.

docs/content/components/networkd.md

@@ -5,4 +5,5 @@ menu:
     parent: components
 ---
 
-Networkd handles all of the host level network configuration. Configuration is defined under the `networking` key.
+Networkd handles all of the host level network configuration.
+Configuration is defined under the `networking` key.

docs/content/components/osctl.md

@@ -7,7 +7,9 @@ menu:
     parent: 'components'
 ---
 
-`osctl` CLI is the client to the [osd](/components/osd) service running on every node. `osctl` should provide enough functionality to be a replacement for typical interactive shell operations. With it you can do things like:
+`osctl` CLI is the client to the [osd](/components/osd) service running on every node.
+`osctl` should provide enough functionality to be a replacement for typical interactive shell operations.
+With it you can do things like:
 
 - `osctl logs <service>` - retrieve container logs
 - `osctl restart <service>` - restart a service

docs/content/configuration/osd.md

@@ -10,12 +10,14 @@ menu:
     weight: 10
 ---
 
-The `osd` service enforces a high level of security by using mutual TLS for authentication and authorization. In this section we will configure mutual TLS by generating the certificates for the servers (`osd`) and clients (`osctl`).
+The `osd` service enforces a high level of security by using mutual TLS for authentication and authorization.
+In this section we will configure mutual TLS by generating the certificates for the servers (`osd`) and clients (`osctl`).
 
 ### Cluster Owners
 
 We recommend that the configuration of `osd` be performed by a cluster owner.
-A cluster owner should be a person of authority within an organization, perhaps a director, manager, or senior member of a team. They are responsible for storing the root CA, and distributing the PKI for authorized cluster administrators.
+A cluster owner should be a person of authority within an organization, perhaps a director, manager, or senior member of a team.
+They are responsible for storing the root CA, and distributing the PKI for authorized cluster administrators.
 
 ### Cluster Administrators
 

docs/content/configuration/userdata.md

@@ -13,7 +13,8 @@ Talos User Data is responsible for the host and Kubernetes configuration, and it
 
 ## Version
 
-``Version`` represents the Talos userdata configuration version. This denotes
+``Version`` represents the Talos userdata configuration version.
+This denotes
 what the schema of the configuration file.
 
 ```yaml
@@ -60,7 +61,8 @@ security:
 #### SA
 
 ``Kubernetes.SA`` contains the certificate/key pair for the default service account.
-This item is optional. If it is not provided, a certificate/key pair will be generated.
+This item is optional.
+If it is not provided, a certificate/key pair will be generated.
 
 ```yaml
 security:
@@ -73,7 +75,8 @@ security:
 #### FrontProxy
 
 ``Kubernetes.FrontProxy`` contains the certificate/key pair for the [Front Proxy](https://kubernetes.io/docs/tasks/access-kubernetes-api/setup-extension-api-server/).
-This item is optional. If it is not provided, a certificate/key pair will be generated.
+This item is optional.
+If it is not provided, a certificate/key pair will be generated.
 
 ```yaml
 security:
@@ -86,7 +89,8 @@ security:
 #### Etcd
 
 ``Kubernetes.Etcd`` contains the certificate/key pair for [etcd](https://kubernetes.io/docs/concepts/overview/components/#etcd).
-This item is optional. If it is not provided, a certificate/key pair will be generated.
+This item is optional.
+If it is not provided, a certificate/key pair will be generated.
 
 ```yaml
 security:
@@ -146,13 +150,15 @@ The following DHCP options are supported:
 
 ##### Routes
 
-``Routes`` is used to specify static routes that may be necessary. This parameter is optional.
+``Routes`` is used to specify static routes that may be necessary.
+This parameter is optional.
 
 ## Services
 
 ### Init
 
-``Init`` allows for the customization of the CNI plugin. This translates to additional host mounts.
+``Init`` allows for the customization of the CNI plugin.
+This translates to additional host mounts.
 
 ```yaml
 services:
@@ -166,8 +172,7 @@ services:
 
 #### ExtraMounts
 
-``Kubelet.ExtraMounts`` allows you to specify additional host mounts that should be presented
+``Kubelet.ExtraMounts`` allows you to specify additional host mounts that should be presented to kubelet.
-to kubelet.
 
 ```yaml
 services:
@@ -232,9 +237,8 @@ services:
 #### InitToken
 
 kubeadm.Inittoken denotes that this node should bootstrap the Kubernetes cluster.
-The token is a UUIDv1 token which means it includes a timestamp of when it was
+The token is a UUIDv1 token which means it includes a timestamp of when it was generated.
-generated. There is a 1 hour TTL associated with this token where it will perform
+There is a 1 hour TTL associated with this token where it will perform a `kubeadm init` to bootstrap the cluster.
-a `kubeadm init` to bootstrap the cluster.
 This token is a UUIDv1 token and can be generated via `osctl gen token`.
 
 This token should only be specified on a single master node.
@@ -287,8 +291,9 @@ services:
 
 #### Endpoints
 
-The endpoints denote the other trustd instances. All trustd instances should
+The endpoints denote the other trustd instances.
-be listed here. These are typically your master nodes.
+All trustd instances should be listed here.
+These are typically your master nodes.
 
 ```yaml
 services:
@@ -310,8 +315,8 @@ services:
 
 #### Server
 
-NTP.Server allows you to customize which NTP server to use. By default it consumes
+NTP.Server allows you to customize which NTP server to use.
-from pool.ntp.org.
+By default it consumes from pool.ntp.org.
 
 ```yaml
 services:
@@ -321,16 +326,16 @@ services:
 
 ## Install
 
-Install is primarily used in bare metal situations. It defines the disk layout and
+Install is primarily used in bare metal situations.
-installation properties.
+It defines the disk layout and installation properties.
 
 ### Boot
 
 #### Device
 
-The device name to use for the `/boot` partition. This should be specified as
+The device name to use for the `/boot` partition.
-the unpartitioned block device. If this parameter is omitted, the value of
+This should be specified as the unpartitioned block device.
-`install.root.device` is used.
+If this parameter is omitted, the value of `install.root.device` is used.
 
 ```yaml
 install:
@@ -340,8 +345,8 @@ install:
 
 #### Size
 
-The size of the `/boot` partition in bytes. If this parameter is omitted, a
+The size of the `/boot` partition in bytes.
-default value of 512MB will be used.
+If this parameter is omitted, a default value of 512MB will be used.
 
 ```yaml
 install:
@@ -351,8 +356,8 @@ install:
 
 #### Kernel
 
-This parameter can be used to specify a custom kernel to use. If this parameter
+This parameter can be used to specify a custom kernel to use.
-is omitted, the most recent Talos release will be used ( fetched from github releases ).
+If this parameter is omitted, the most recent Talos release will be used ( fetched from github releases ).
 
 ```yaml
 install:
@@ -364,8 +369,8 @@ install:
 
 #### Initramfs
 
-This parameter can be used to specify a custom initramfs to use. If this parameter
+This parameter can be used to specify a custom initramfs to use.
-is omitted, the most recent Talos release will be used ( fetched from github releases ).
+If this parameter is omitted, the most recent Talos release will be used ( fetched from github releases ).
 
 ```yaml
 install:
@@ -380,8 +385,9 @@ install:
 <!-- markdownlint-disable MD024 -->
 #### Device
 
-``Device`` specifies the device name to use for the `/var` partition. This should be specified as the
+``Device`` specifies the device name to use for the `/var` partition.
-unpartitioned block device. If this parameter is omitted, the value of `install.root.device` is used.
+This should be specified as the unpartitioned block device.
+If this parameter is omitted, the value of `install.root.device` is used.
 
 ```yaml
 install:
@@ -392,8 +398,9 @@ install:
 <!-- markdownlint-disable MD024 -->
 #### Size
 
-``Size`` defines the size of the `/var` partition in bytes. If this parameter is omitted, a default
+``Size`` defines the size of the `/var` partition in bytes.
-value of 1GB will be used. This partition will auto extend to consume the remainder of the unpartitioned space on the disk.
+If this parameter is omitted, a default value of 1GB will be used.
+This partition will auto extend to consume the remainder of the unpartitioned space on the disk.
 
 ```yaml
 install:
@@ -421,8 +428,8 @@ install:
 
 ### ExtraDevices
 
-``ExtraDevices`` allows for the extension of the partitioning scheme on the specified
+``ExtraDevices`` allows for the extension of the partitioning scheme on the specified device.
-device. These new partitions will be formatted as `xfs` filesystems.
+These new partitions will be formatted as `xfs` filesystems.
 
 ```yaml
 install:

docs/content/configuration/workers.md

@@ -10,7 +10,8 @@ menu:
 ---
 
 Configuring the worker nodes is simple in comparison to configuring the master nodes.
-Using the `trustd` API, worker nodes submit a `CSR`, and, if authenticated, receive a valid `osd` certificate. Similarly, using a `kubeadm` token, the node joins an existing cluster.
+Using the `trustd` API, worker nodes submit a `CSR`, and, if authenticated, receive a valid `osd` certificate.
+Similarly, using a `kubeadm` token, the node joins an existing cluster.
 
 We need to specify:
 

docs/content/guides/azure.md

@@ -9,9 +9,8 @@ menu:
 
 ## Image Creation
 
-For each [Talos release](https://github.com/talos-systems/talos/releases),
+For each [Talos release](https://github.com/talos-systems/talos/releases), we provide an Azure compatible vhd (`azure.tar.gz`).
-we provide an Azure compatible vhd (`azure.tar.gz`).  If you want to build
+If you want to build the image locally, you can do so by running:
-the image locally, you can do so by running:
 
 ```bash
 make installer
@@ -22,9 +21,8 @@ This will produce `build/azure.tar.gz`.
 
 ## Environment Setup
 
-Before proceeding, you'll want to make sure you have `osctl` available and the
+Before proceeding, you'll want to make sure you have `osctl` available and the azure cli `az` installed and configured.
-azure cli `az` installed and configured. `osctl` is published on each release
+`osctl` is published on each release and is available on our releases page [Talos release](https://github.com/talos-systems/talos/releases).
-and is available on our releases page [Talos release](https://github.com/talos-systems/talos/releases).
 If you want to build it locally, you can do so by running:
 
 ```bash
@@ -47,8 +45,7 @@ LOCATION=${LOCATION:-westus2}
 
 ## Upload Image
 
-After downloading or creating the image locally, we'll want to upload it to
+After downloading or creating the image locally, we'll want to upload it to Azure and create an image.
-Azure and create an image.
 
 ```bash
 # Create resource group
@@ -97,8 +94,8 @@ az network nsg rule create -g $GROUP --nsg-name talos -n kube --priority 1004 --
 
 ## Cluster Configuration
 
-After getting the network security group set up, we'll need to allocate public
+After getting the network security group set up, we'll need to allocate public IPs for our master nodes.
-IPs for our master nodes. The example below assumes a HA control plane of 3 nodes.
+The example below assumes a HA control plane of 3 nodes.
 You can adjust this for your needs.
 
 ```bash
@@ -153,5 +150,5 @@ osctl --talosconfig ./talosconfig kubeconfig > kubeconfig
 kubectl --kubeconfig ./kubeconfig get nodes
 ```
 
-You will need to apply a PSP and CNI configuration. More details can be found
+You will need to apply a PSP and CNI configuration.
-in the [getting started](/docs/guides/getting_started) guide.
+More details can be found in the [getting started](/docs/guides/getting_started) guide.

docs/content/guides/bare_metal.md

@@ -11,15 +11,18 @@ menu:
 
 When considering Talos for production, the best way to get started is by using the `osctl config generate` command.
 
-Talos requires 3 static IPs, one for each of the master nodes. After allocating these addresses, you can generate the necessary configs with the following commands:
+Talos requires 3 static IPs, one for each of the master nodes.
+After allocating these addresses, you can generate the necessary configs with the following commands:
 
 ```bash
 osctl config generate <cluster name> <master-1 ip,master-2 ip, master-3 ip>
 ```
 
-This will generate 5 files - `master-{1,2,3}.yaml`, `worker.yaml`, and `talosconfig`. The master and worker config files contain just enough config to bootstrap your cluster, and can be further customized as necessary.
+This will generate 5 files - `master-{1,2,3}.yaml`, `worker.yaml`, and `talosconfig`.
+The master and worker config files contain just enough config to bootstrap your cluster, and can be further customized as necessary.
 
-These config files should be supplied as machine userdata or some internally accessible url so they can be downloaded during machine bootup. When specifying a remote location to download userdata from, the kernel parameter `talos.userdata=http://myurl.com`.
+These config files should be supplied as machine userdata or some internally accessible url so they can be downloaded during machine bootup.
+When specifying a remote location to download userdata from, the kernel parameter `talos.userdata=http://myurl.com`.
 
 An iPXE server such as [coreos/Matchbox](https://github.com/poseidon/matchbox) is recommended.
 
@@ -40,14 +43,20 @@ Talos also enforces some minimum requirements from the KSPP (kernel self-protect
 
 After the machines have booted up, you'll want to manage your Talos config file.
 
-The `osctl` tool looks for its configuration in `~/.talos/config` by default. The configuration file location can also be specified at runtime via `osctl --talosconfig myconfigfile`. In the previous step, the Talos configuration was generated in your working directory as `talosconfig`.
+The `osctl` tool looks for its configuration in `~/.talos/config` by default.
+The configuration file location can also be specified at runtime via `osctl --talosconfig myconfigfile`.
+In the previous step, the Talos configuration was generated in your working directory as `talosconfig`.
 
-By default, the Talos configuration points to a single node. This can be overridden at runtime via `--target <ip>` flag so you can point to another node in your cluster.
+By default, the Talos configuration points to a single node.
+This can be overridden at runtime via `--target <ip>` flag so you can point to another node in your cluster.
 
-Next, we'll need to generate the kubeconfig for our cluster. This can be achieved by runng `osctl kubeconfig`.
+Next, we'll need to generate the kubeconfig for our cluster.
+This can be achieved by runng `osctl kubeconfig`.
 
 ## Finalizing Kubernetes Setup
 
-Once your machines boot up, you will want to apply a Pod Security Policy (PSP). There is a basic example that can be found [here](https://raw.githubusercontent.com/talos-systems/talos/master/hack/dev/manifests/psp.yaml) or you can create your own.
+Once your machines boot up, you will want to apply a Pod Security Policy (PSP).
+There is a basic example that can be found [here](https://raw.githubusercontent.com/talos-systems/talos/master/hack/dev/manifests/psp.yaml) or you can create your own.
 
-Finally, you'll want to apply a CNI plugin. You'll want to take note of the kubeadm `networking.podsubnet` parameter and ensure the network range matches up.
+Finally, you'll want to apply a CNI plugin.
+You'll want to take note of the kubeadm `networking.podsubnet` parameter and ensure the network range matches up.

docs/content/talos.md

@@ -8,7 +8,9 @@ menu:
     weight: 1
 ---
 
-**Talos** is a modern OS designed to be secure, immutable, and minimal. All system management is done via an API, and there is no shell or interactive console. Some of the capabilities and benefits provided by Talos include:
+**Talos** is a modern OS designed to be secure, immutable, and minimal.
+All system management is done via an API, and there is no shell or interactive console.
+Some of the capabilities and benefits provided by Talos include:
 
 - **Security**: Talos reduces your attack surface by practicing the Principle of Least Privilege (PoLP) and by securing the API with mutual TLS (mTLS) authentication.
 - **Predictability**: Talos eliminates unneeded variables and reduces unknown factors in your environment by employing immutable infrastructure ideology.

docs/content/use_cases/edge.md

@@ -8,13 +8,8 @@ menu:
 
 ## Edge Computing
 
-Edge computing, where the data and compute power is distributed to different
+Edge computing, where the data and compute power is distributed to different physical locations where it is needed, comes with many unique management challenges.
-physical locations where it is needed, comes with many unique management
+Applying system updates to traditional operating systems can be slow and use a lot of bandwidth, and losing remote access to an edge node because of a failed update can be catastrophic.
-challenges. Applying system updates to traditional operating systems can be
-slow and use a lot of bandwidth, and losing remote access to an edge node
-because of a failed update can be catastrophic.
 
-Talos makes computing at the edge safer and faster. The minimal operating
+Talos makes computing at the edge safer and faster.
-system requires less bandwidth to deploy and update, and the immutable Talos OS
+The minimal operating system requires less bandwidth to deploy and update, and the immutable Talos OS image ("no moving parts") makes updates easier to test, and more reliable upon deployment.
-image ("no moving parts") makes updates easier to test, and more reliable upon
-deployment.

docs/content/use_cases/multi-cloud.md

@@ -8,13 +8,8 @@ menu:
 
 ## Multi-cloud Kubernetes
 
-Running a large-scale Kubernetes cluster across multiple cloud providers or
+Running a large-scale Kubernetes cluster across multiple cloud providers or forms of infrastructure can solve some important problems for your business, but it can also create new ones.
-forms of infrastructure can solve some important problems for your business,
+Different base OSes, different versions of critical components, and different upgrade cycles can contribute to instability and hard-to-troubleshoot problems.
-but it can also create new ones. Different base OSes, different versions of
-critical components, and different upgrade cycles can contribute to instability
-and hard-to-troubleshoot problems.
 
-Talos has been built from the ground up with multi-cloud operations teams in
+Talos has been built from the ground up with multi-cloud operations teams in mind, giving you a single platform that is compatible with multiple cloud providers.
-mind, giving you a single platform that is compatible with multiple cloud
+In the future, you will be able to manage all of your Talos-based environments from a single control plane.
-providers. In the future, you will be able to manage all of your Talos-based
-environments from a single control plane.

docs/content/use_cases/serverless.md

@@ -8,13 +8,8 @@ menu:
 
 ## Serverless Infrastructure
 
-In a "serverless" environment where units of code are decomposed
+In a "serverless" environment where units of code are decomposed down to the function level, demand may scale up and down rapidly as different applications make different demands on the underlying infrastructure.
-down to the function level, demand may scale up and down rapidly as different
+Managing the underlying infrastructure in an efficient and automated way is critical to realize the benefits of running a serverless platform.
-applications make different demands on the underlying infrastructure. Managing
-the underlying infrastructure in an efficient and automated way is critical
-to realize the benefits of running a serverless platform.
 
-Due to its minimal footprint and design, Talos hosts can be scaled up and down
+Due to its minimal footprint and design, Talos hosts can be scaled up and down much faster than traditional OSes, which means your infrastructure can be more responsive to changes in demand.
-much faster than traditional OSes, which means your infrastructure can be more
+Cluster management can be automated to make the most efficient use of limited resources.
-responsive to changes in demand. Cluster management can be automated to make the
-most efficient use of limited resources.

docs/proposals/YYYYMMDD-TEMPLATE.md

@@ -28,5 +28,5 @@ Author(s): [Author Name, Co-Author Name]
 
 ## Open issues (if applicable)
 
-[A discussion of issues relating to this proposal for which the author does not
+[A discussion of issues relating to this proposal for which the author does not know the solution.]
-know the solution. This section may be omitted if there are none.]
+[This section may be omitted if there are none.]