add pre-commit hook to facilitate local testing (#9158)

* add pre-commit hook configuration

* add tmp.md to .gitignore

* describe the use of pre-commit hook in CONTRIBUTING.md

* fix docs/integration.md errors identified by markdownlint

* fix docs/<file>.md errors identified by markdownlint

* docs/azure-csi.md
* docs/azure.md
* docs/bootstrap-os.md
* docs/calico.md
* docs/debian.md
* docs/fcos.md
* docs/vagrant.md
* docs/gcp-lb.md
* docs/kubernetes-apps/registry.md
* docs/setting-up-your-first-cluster.md
* docs/vagrant.md
* docs/vars.md

* fix contrib/<file>.md errors identified by markdownlint

.gitignore

@@ -112,3 +112,4 @@ roles/**/molecule/**/__pycache__/
 
 # Temp location used by our scripts
 scripts/tmp/
+tmp.md

.markdownlint.yaml

@@ -1,2 +1,3 @@
 ---
 MD013: false
+MD029: false

.pre-commit-config.yaml

@@ -0,0 +1,48 @@
+---
+repos:
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.27.1
+    hooks:
+      - id: yamllint
+        args: [--strict]
+
+  - repo: https://github.com/markdownlint/markdownlint
+    rev: v0.11.0
+    hooks:
+      - id: markdownlint
+        args: [ -r, "~MD013,~MD029" ]
+        exclude: "^.git"
+
+  - repo: local
+    hooks:
+      - id: ansible-lint
+        name: ansible-lint
+        entry: ansible-lint -v
+        language: python
+        pass_filenames: false
+        additional_dependencies:
+          - .[community]
+
+      - id: ansible-syntax-check
+        name: ansible-syntax-check
+        entry: env ANSIBLE_INVENTORY=inventory/local-tests.cfg ANSIBLE_REMOTE_USER=root ANSIBLE_BECOME="true" ANSIBLE_BECOME_USER=root ANSIBLE_VERBOSITY="3" ansible-playbook --syntax-check
+        language: python
+        files: "^cluster.yml|^upgrade-cluster.yml|^reset.yml|^extra_playbooks/upgrade-only-k8s.yml"
+
+      - id: tox-inventory-builder
+        name: tox-inventory-builder
+        entry: bash -c "cd contrib/inventory_builder && tox"
+        language: python
+        pass_filenames: false
+
+      - id: check-readme-versions
+        name: check-readme-versions
+        entry: tests/scripts/check_readme_versions.sh
+        language: script
+        pass_filenames: false
+
+      - id: ci-matrix
+        name: ci-matrix
+        entry: tests/scripts/md-table/test.sh
+        language: script
+        pass_filenames: false

CONTRIBUTING.md

@@ -16,7 +16,12 @@ pip install -r tests/requirements.txt
 
 #### Linting
 
-Kubespray uses `yamllint` and `ansible-lint`. To run them locally use `yamllint .` and `ansible-lint`. It is a good idea to add call these tools as part of your pre-commit hook and avoid a lot of back end forth on fixing linting issues (<https://support.gitkraken.com/working-with-repositories/githooksexample/>).
+Kubespray uses [pre-commit](https://pre-commit.com) hook configuration to run several linters, please install this tool and use it to run validation tests before submitting a PR.
+
+```ShellSession
+pre-commit install
+pre-commit run -a  # To run pre-commit hook on all files in the repository, even if they were not modified
+```
 
 #### Molecule
 
@@ -33,7 +38,9 @@ Vagrant with VirtualBox or libvirt driver helps you to quickly spin test cluster
 1. Submit an issue describing your proposed change to the repo in question.
 2. The [repo owners](OWNERS) will respond to your issue promptly.
 3. Fork the desired repo, develop and test your code changes.
-4. Sign the CNCF CLA (<https://git.k8s.io/community/CLA.md#the-contributor-license-agreement>)
+4. Install [pre-commit](https://pre-commit.com) and install it in your development repo.
-5. Submit a pull request.
+5. Addess any pre-commit validation failures.
-6. Work with the reviewers on their suggestions.
+6. Sign the CNCF CLA (<https://git.k8s.io/community/CLA.md#the-contributor-license-agreement>)
-7. Ensure to rebase to the HEAD of your target branch and squash un-necessary commits (<https://blog.carbonfive.com/always-squash-and-rebase-your-git-commits/>) before final merger of your contribution.
+7. Submit a pull request.
+8. Work with the reviewers on their suggestions.
+9. Ensure to rebase to the HEAD of your target branch and squash un-necessary commits (<https://blog.carbonfive.com/always-squash-and-rebase-your-git-commits/>) before final merger of your contribution.

contrib/network-storage/glusterfs/roles/glusterfs/README.md

@@ -14,12 +14,16 @@ This role performs basic installation and setup of Gluster, but it does not conf
 
 Available variables are listed below, along with default values (see `defaults/main.yml`):
 
-    glusterfs_default_release: ""
+```yaml
+glusterfs_default_release: ""
+```
 
 You can specify a `default_release` for apt on Debian/Ubuntu by overriding this variable. This is helpful if you need a different package or version for the main GlusterFS packages (e.g. GlusterFS 3.5.x instead of 3.2.x with the `wheezy-backports` default release on Debian Wheezy).
 
-    glusterfs_ppa_use: yes
+```yaml
-    glusterfs_ppa_version: "3.5"
+glusterfs_ppa_use: yes
+glusterfs_ppa_version: "3.5"
+```
 
 For Ubuntu, specify whether to use the official Gluster PPA, and which version of the PPA to use. See Gluster's [Getting Started Guide](https://docs.gluster.org/en/latest/Quick-Start-Guide/Quickstart/) for more info.
 
@@ -29,9 +33,11 @@ None.
 
 ## Example Playbook
 
+```yaml
     - hosts: server
       roles:
         - geerlingguy.glusterfs
+```
 
 For a real-world use example, read through [Simple GlusterFS Setup with Ansible](http://www.jeffgeerling.com/blog/simple-glusterfs-setup-ansible), a blog post by this role's author, which is included in Chapter 8 of [Ansible for DevOps](https://www.ansiblefordevops.com/).
 

contrib/terraform/aws/README.md

@@ -36,8 +36,7 @@ terraform apply -var-file=credentials.tfvars
 ```
 
 - Terraform automatically creates an Ansible Inventory file called `hosts` with the created infrastructure in the directory `inventory`
-- Ansible will automatically generate an ssh config file for your bastion hosts. To connect to hosts with ssh using bastion host use generated ssh-bastion.conf.
+- Ansible will automatically generate an ssh config file for your bastion hosts. To connect to hosts with ssh using bastion host use generated `ssh-bastion.conf`. Ansible automatically detects bastion and changes `ssh_args`
-  Ansible automatically detects bastion and changes ssh_args  
 
 ```commandline
 ssh -F ./ssh-bastion.conf user@$ip

contrib/terraform/exoscale/README.md

@@ -31,9 +31,7 @@ The setup looks like following
 
 ## Requirements
 
-* Terraform 0.13.0 or newer
+* Terraform 0.13.0 or newer (0.12 also works if you modify the provider block to include version and remove all `versions.tf` files)
-
-*0.12 also works if you modify the provider block to include version and remove all `versions.tf` files*
 
 ## Quickstart
 

contrib/terraform/vsphere/README.md

@@ -35,9 +35,7 @@ This setup assumes that the DHCP is disabled in the vSphere cluster and IP addre
 
 ## Requirements
 
-* Terraform 0.13.0 or newer
+* Terraform 0.13.0 or newer (0.12 also works if you modify the provider block to include version and remove all `versions.tf` files)
-
-*0.12 also works if you modify the provider block to include version and remove all `versions.tf` files*
 
 ## Quickstart
 

docs/azure-csi.md

@@ -57,19 +57,28 @@ The name of the network security group your instances are in, can be retrieved v
 These will have to be generated first:
 
 - Create an Azure AD Application with:
-`az ad app create --display-name kubespray --identifier-uris http://kubespray --homepage http://kubespray.com --password CLIENT_SECRET`
+
+  ```ShellSession
+  az ad app create --display-name kubespray --identifier-uris http://kubespray --homepage http://kubespray.com --password CLIENT_SECRET
+  ```
 
 Display name, identifier-uri, homepage and the password can be chosen
 
 Note the AppId in the output.
 
 - Create Service principal for the application with:
-`az ad sp create --id AppId`
+
+  ```ShellSession
+  az ad sp create --id AppId
+  ```
 
 This is the AppId from the last command
 
 - Create the role assignment with:
-`az role assignment create --role "Owner" --assignee http://kubespray --subscription SUBSCRIPTION_ID`
+
+  ```ShellSession
+  az role assignment create --role "Owner" --assignee http://kubespray --subscription SUBSCRIPTION_ID
+  ```
 
 azure\_csi\_aad\_client\_id must be set to the AppId, azure\_csi\_aad\_client\_secret is your chosen secret.
 

docs/azure.md

@@ -71,14 +71,27 @@ The name of the resource group that contains the route table.  Defaults to `azur
 These will have to be generated first:
 
 - Create an Azure AD Application with:
-`az ad app create --display-name kubernetes --identifier-uris http://kubernetes --homepage http://example.com --password CLIENT_SECRET`
+
+  ```ShellSession
+   az ad app create --display-name kubernetes --identifier-uris http://kubernetes --homepage http://example.com --password CLIENT_SECRET
+  ```
+
 display name, identifier-uri, homepage and the password can be chosen
 Note the AppId in the output.
+
 - Create Service principal for the application with:
-`az ad sp create --id AppId`
+
+  ```ShellSession
+  az ad sp create --id AppId
+  ```
+
 This is the AppId from the last command
+
 - Create the role assignment with:
-`az role assignment create --role "Owner" --assignee http://kubernetes --subscription SUBSCRIPTION_ID`
+
+  ```ShellSession
+  az role assignment create --role "Owner" --assignee http://kubernetes --subscription SUBSCRIPTION_ID
+  ```
 
 azure\_aad\_client\_id must be set to the AppId, azure\_aad\_client\_secret is your chosen secret.
 

docs/bootstrap-os.md

@@ -48,11 +48,13 @@ The `kubespray-defaults` role is expected to be run before this role.
 
 Remember to disable fact gathering since Python might not be present on hosts.
 
-    - hosts: all
+```yaml
-      gather_facts: false  # not all hosts might be able to run modules yet
+- hosts: all
-      roles:
+  gather_facts: false  # not all hosts might be able to run modules yet
-         - kubespray-defaults
+  roles:
-         - bootstrap-os
+    - kubespray-defaults
+    - bootstrap-os
+```
 
 ## License
 

docs/calico.md

@@ -124,8 +124,7 @@ You need to edit your inventory and add:
 * `calico_rr` group with nodes in it. `calico_rr` can be combined with
   `kube_node` and/or `kube_control_plane`. `calico_rr` group also must be a child
    group of `k8s_cluster` group.
-* `cluster_id` by route reflector node/group (see details
+* `cluster_id` by route reflector node/group (see details [here](https://hub.docker.com/r/calico/routereflector/))
-[here](https://hub.docker.com/r/calico/routereflector/))
 
 Here's an example of Kubespray inventory with standalone route reflectors:
 

docs/debian.md

@@ -3,34 +3,39 @@
 Debian Jessie installation Notes:
 
 - Add
-  
+
-  ```GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"```
+  ```ini
-  
+  GRUB_CMDLINE_LINUX="cgroup_enable=memory swapaccount=1"
-  to /etc/default/grub. Then update with
-  
-  ```ShellSession
-   sudo update-grub
-   sudo update-grub2
-   sudo reboot
   ```
-  
+
+  to `/etc/default/grub`. Then update with
+
+  ```ShellSession
+  sudo update-grub
+  sudo update-grub2
+  sudo reboot
+  ```
+
 - Add the [backports](https://backports.debian.org/Instructions/) which contain Systemd 2.30 and update Systemd.
-  
+
-  ```apt-get -t jessie-backports install systemd```
+  ```ShellSession
-  
+  apt-get -t jessie-backports install systemd
+  ```
+
   (Necessary because the default Systemd version (2.15) does not support the "Delegate" directive in service files)
-  
+
 - Add the Ansible repository and install Ansible to get a proper version
 
   ```ShellSession
   sudo add-apt-repository ppa:ansible/ansible
   sudo apt-get update
   sudo apt-get install ansible
-
   ```
 
 - Install Jinja2 and Python-Netaddr
 
-  ```sudo apt-get install python-jinja2=2.8-1~bpo8+1 python-netaddr```
+  ```ShellSession
-  
+  sudo apt-get install python-jinja2=2.8-1~bpo8+1 python-netaddr
+  ```
+
 Now you can continue with [Preparing your deployment](getting-started.md#starting-custom-deployment)

docs/fcos.md

@@ -54,7 +54,7 @@ Prepare ignition and serve via http (a.e. python -m http.server )
 
 ### create guest
 
-```shell script
+```ShellSeasion
 machine_name=myfcos1
 ignition_url=http://mywebserver/fcos.ign
 

docs/gcp-lb.md

@@ -2,15 +2,19 @@
 
 Google Cloud Platform can be used for creation of Kubernetes Service Load Balancer.
 
-This feature is able to deliver by adding parameters to kube-controller-manager and kubelet. You need specify:
+This feature is able to deliver by adding parameters to `kube-controller-manager` and `kubelet`. You need specify:
 
+```ShellSession
     --cloud-provider=gce
     --cloud-config=/etc/kubernetes/cloud-config
+```
 
-To get working it in kubespray, you need to add tag to GCE instances and specify it in kubespray group vars and also set cloud_provider to gce. So for example, in file group_vars/all/gcp.yml:
+To get working it in kubespray, you need to add tag to GCE instances and specify it in kubespray group vars and also set `cloud_provider` to `gce`. So for example, in file `group_vars/all/gcp.yml`:
 
+```yaml
     cloud_provider: gce
     gce_node_tags: k8s-lb
+```
 
-When you will setup it and create SVC in Kubernetes with type=LoadBalancer, cloud provider will create public IP and will set firewall.
+When you will setup it and create SVC in Kubernetes with `type=LoadBalancer`, cloud provider will create public IP and will set firewall.
 Note: Cloud provider run under VM service account, so this account needs to have correct permissions to be able to create all GCP resources.

docs/integration.md

@@ -6,84 +6,100 @@
      * List of all forked repos could be retrieved from github page of original project.
 
 2. Add **forked repo** as submodule to desired folder in your existent ansible repo (for example 3d/kubespray):
-  ```git submodule add https://github.com/YOUR_GITHUB/kubespray.git kubespray```
+
-  Git will create `.gitmodules` file in your existent ansible repo:
+   ```ShellSession
+   git submodule add https://github.com/YOUR_GITHUB/kubespray.git kubespray
+   ```
+
+   Git will create `.gitmodules` file in your existent ansible repo:
 
    ```ini
    [submodule "3d/kubespray"]
-         path = 3d/kubespray
+          path = 3d/kubespray
-         url = https://github.com/YOUR_GITHUB/kubespray.git
+          url = https://github.com/YOUR_GITHUB/kubespray.git
    ```
 
 3. Configure git to show submodule status:
-```git config --global status.submoduleSummary true```
+
+   ```ShellSession
+   git config --global status.submoduleSummary true
+   ```
 
 4. Add *original* kubespray repo as upstream:
-```cd kubespray && git remote add upstream https://github.com/kubernetes-sigs/kubespray.git```
+
+   ```ShellSession
+   cd kubespray && git remote add upstream https://github.com/kubernetes-sigs/kubespray.git
+   ```
 
 5. Sync your master branch with upstream:
 
    ```ShellSession
-      git checkout master
+   git checkout master
-      git fetch upstream
+   git fetch upstream
-      git merge upstream/master
+   git merge upstream/master
-      git push origin master
+   git push origin master
    ```
 
 6. Create a new branch which you will use in your working environment:
-```git checkout -b work```
+
+   ```ShellSession
+   git checkout -b work
+   ```
+
     ***Never*** use master branch of your repository for your commits.
 
 7. Modify path to library and roles in your ansible.cfg file (role naming should be unique, you may have to rename your existent roles if they have same names as kubespray project),
    if you had roles in your existing ansible project before, you can add the path to those separated with `:`:
 
-8. ```ini
+   ```ini
    ...
    library       = ./library/:3d/kubespray/library/
    roles_path    = ./roles/:3d/kubespray/roles/
    ...
    ```
 
-9. Copy and modify configs from kubespray `group_vars` folder to corresponding `group_vars` folder in your existent project.
+8. Copy and modify configs from kubespray `group_vars` folder to corresponding `group_vars` folder in your existent project.
-You could rename *all.yml* config to something else, i.e. *kubespray.yml* and create corresponding group in your inventory file, which will include all hosts groups related to kubernetes setup.
 
-10. Modify your ansible inventory file by adding mapping of your existent groups (if any) to kubespray naming.
+   You could rename *all.yml* config to something else, i.e. *kubespray.yml* and create corresponding group in your inventory file, which will include all hosts groups related to kubernetes setup.
+
+9. Modify your ansible inventory file by adding mapping of your existent groups (if any) to kubespray naming.
     For example:
 
-    ```ini
+   ```ini
-      ...
+   ...
-      #Kargo groups:
+   #Kubespray groups:
-      [kube_node:children]
+   [kube_node:children]
-      kubenode
+   kubenode
 
-      [k8s_cluster:children]
+   [k8s_cluster:children]
-      kubernetes
+   kubernetes
 
-      [etcd:children]
+   [etcd:children]
-      kubemaster
+   kubemaster
-      kubemaster-ha
+   kubemaster-ha
 
-      [kube_control_plane:children]
+   [kube_control_plane:children]
-      kubemaster
+   kubemaster
-      kubemaster-ha
+   kubemaster-ha
 
-      [kubespray:children]
+   [kubespray:children]
-      kubernetes
+   kubernetes
-      ```
+   ```
 
-      * Last entry here needed to apply kubespray.yml config file, renamed from all.yml of kubespray project.
+* Last entry here needed to apply kubespray.yml config file, renamed from all.yml of kubespray project.
 
-11. Now you can include kubespray tasks in you existent playbooks by including cluster.yml file:
+10. Now you can include kubespray tasks in you existent playbooks by including cluster.yml file:
 
-     ```yml
+    ```yml
-     - name: Import kubespray playbook
+    - name: Import kubespray playbook
-       ansible.builtin.import_playbook: 3d/kubespray/cluster.yml
+      ansible.builtin.import_playbook: 3d/kubespray/cluster.yml
-     ```
+    ```
 
-     Or your could copy separate tasks from cluster.yml into your ansible repository.
+    Or your could copy separate tasks from cluster.yml into your ansible repository.
 
-12. Commit changes to your ansible repo. Keep in mind, that submodule folder is just a link to the git commit hash of your forked repo.
+11. Commit changes to your ansible repo. Keep in mind, that submodule folder is just a link to the git commit hash of your forked repo.
-When you update your "work" branch you need to commit changes to ansible repo as well.
+
+    When you update your "work" branch you need to commit changes to ansible repo as well.
 Other members of your team should use ```git submodule sync```, ```git submodule update --init``` to get actual code from submodule.
 
 ## Contributing
@@ -95,37 +111,78 @@ If you made useful changes or fixed a bug in existent kubespray repo, use this f
 2. Change working directory to git submodule directory (3d/kubespray).
 
 3. Setup desired user.name and user.email for submodule.
-If kubespray is only one submodule in your repo you could use something like:
+
-```git submodule foreach --recursive 'git config user.name "First Last" && git config user.email "your-email-address@used.for.cncf"'```
+   If kubespray is only one submodule in your repo you could use something like:
+
+   ```ShellSession
+   git submodule foreach --recursive 'git config user.name "First Last" && git config user.email "your-email-address@used.for.cncf"'
+   ```
 
 4. Sync with upstream master:
 
    ```ShellSession
-    git fetch upstream
+   git fetch upstream
-    git merge upstream/master
+   git merge upstream/master
-    git push origin master
+   git push origin master
-     ```
+   ```
 
 5. Create new branch for the specific fixes that you want to contribute:
-```git checkout -b fixes-name-date-index```
+
-Branch name should be self explaining to you, adding date and/or index will help you to track/delete your old PRs.
+   ```ShellSession
+   git checkout -b fixes-name-date-index
+   ```
+
+   Branch name should be self explaining to you, adding date and/or index will help you to track/delete your old PRs.
 
 6. Find git hash of your commit in "work" repo and apply it to newly created "fix" repo:
 
-     ```ShellSession
+   ```ShellSession
-     git cherry-pick <COMMIT_HASH>
+   git cherry-pick <COMMIT_HASH>
-     ```
+   ```
 
-7. If you have several temporary-stage commits - squash them using [```git rebase -i```](https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit)
+7. If you have several temporary-stage commits - squash them using [git rebase -i](https://eli.thegreenplace.net/2014/02/19/squashing-github-pull-requests-into-a-single-commit)
-Also you could use interactive rebase (```git rebase -i HEAD~10```) to delete commits which you don't want to contribute into original repo.
+
+   Also you could use interactive rebase
+
+   ```ShellSession
+   git rebase -i HEAD~10
+   ```
+
+   to delete commits which you don't want to contribute into original repo.
 
 8. When your changes is in place, you need to check upstream repo one more time because it could be changed during your work.
-Check that you're on correct branch:
-```git status```
-And pull changes from upstream (if any):
-```git pull --rebase upstream master```
 
-9. Now push your changes to your **fork** repo with ```git push```. If your branch doesn't exists on github, git will propose you to use something like ```git push --set-upstream origin fixes-name-date-index```.
+   Check that you're on correct branch:
 
-10. Open you forked repo in browser, on the main page you will see proposition to create pull request for your newly created branch. Check proposed diff of your PR. If something is wrong you could safely delete "fix" branch on github using ```git push origin --delete fixes-name-date-index```, ```git branch -D fixes-name-date-index``` and start whole process from the beginning.
+   ```ShellSession
-If everything is fine - add description about your changes (what they do and why they're needed) and confirm pull request creation.
+   git status
+   ```
+
+   And pull changes from upstream (if any):
+
+   ```ShellSession
+   git pull --rebase upstream master
+   ```
+
+9. Now push your changes to your **fork** repo with
+
+   ```ShellSession
+   git push
+   ```
+
+   If your branch doesn't exists on github, git will propose you to use something like
+
+   ```ShellSession
+   git push --set-upstream origin fixes-name-date-index
+   ```
+
+10. Open you forked repo in browser, on the main page you will see proposition to create pull request for your newly created branch. Check proposed diff of your PR. If something is wrong you could safely delete "fix" branch on github using
+
+    ```ShellSession
+    git push origin --delete fixes-name-date-index
+    git branch -D fixes-name-date-index
+    ```
+
+    and start whole process from the beginning.
+
+    If everything is fine - add description about your changes (what they do and why they're needed) and confirm pull request creation.

docs/kubernetes-apps/registry.md

@@ -29,8 +29,7 @@ use Kubernetes's `PersistentVolume` abstraction. The following template is
 expanded by `salt` in the GCE cluster turnup, but can easily be adapted to
 other situations:
 
-<!-- BEGIN MUNGE: EXAMPLE registry-pv.yaml.in -->
+```yaml
-``` yaml
 kind: PersistentVolume
 apiVersion: v1
 metadata:
@@ -46,7 +45,6 @@ spec:
     fsType: "ext4"
 {% endif %}
 ```
-<!-- END MUNGE: EXAMPLE registry-pv.yaml.in -->
 
 If, for example, you wanted to use NFS you would just need to change the
 `gcePersistentDisk` block to `nfs`. See
@@ -68,8 +66,7 @@ Now that the Kubernetes cluster knows that some storage exists, you can put a
 claim on that storage. As with the `PersistentVolume` above, you can start
 with the `salt` template:
 
-<!-- BEGIN MUNGE: EXAMPLE registry-pvc.yaml.in -->
+```yaml
-``` yaml
 kind: PersistentVolumeClaim
 apiVersion: v1
 metadata:
@@ -82,7 +79,6 @@ spec:
     requests:
       storage: {{ pillar['cluster_registry_disk_size'] }}
 ```
-<!-- END MUNGE: EXAMPLE registry-pvc.yaml.in -->
 
 This tells Kubernetes that you want to use storage, and the `PersistentVolume`
 you created before will be bound to this claim (unless you have other
@@ -93,8 +89,7 @@ gives you the right to use this storage until you release the claim.
 
 Now we can run a Docker registry:
 
-<!-- BEGIN MUNGE: EXAMPLE registry-rc.yaml -->
+```yaml
-``` yaml
 apiVersion: v1
 kind: ReplicationController
 metadata:
@@ -138,7 +133,6 @@ spec:
         persistentVolumeClaim:
           claimName: kube-registry-pvc
 ```
-<!-- END MUNGE: EXAMPLE registry-rc.yaml -->
 
 *Note:* that if you have set multiple replicas, make sure your CSI driver has support for the `ReadWriteMany` accessMode.
 
@@ -146,8 +140,7 @@ spec:
 
 Now that we have a registry `Pod` running, we can expose it as a Service:
 
-<!-- BEGIN MUNGE: EXAMPLE registry-svc.yaml -->
+```yaml
-``` yaml
 apiVersion: v1
 kind: Service
 metadata:
@@ -164,7 +157,6 @@ spec:
     port: 5000
     protocol: TCP
 ```
-<!-- END MUNGE: EXAMPLE registry-svc.yaml -->
 
 ## Expose the registry on each node
 
@@ -172,8 +164,7 @@ Now that we have a running `Service`, we need to expose it onto each Kubernetes
 `Node` so that Docker will see it as `localhost`. We can load a `Pod` on every
 node by creating following daemonset.
 
-<!-- BEGIN MUNGE: EXAMPLE ../../saltbase/salt/kube-registry-proxy/kube-registry-proxy.yaml -->
+```yaml
-``` yaml
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:
@@ -207,7 +198,6 @@ spec:
           containerPort: 80
           hostPort: 5000
 ```
-<!-- END MUNGE: EXAMPLE ../../saltbase/salt/kube-registry-proxy/kube-registry-proxy.yaml -->
 
 When modifying replication-controller, service and daemon-set definitions, take
 care to ensure *unique* identifiers for the rc-svc couple and the daemon-set.
@@ -219,7 +209,7 @@ This ensures that port 5000 on each node is directed to the registry `Service`.
 You should be able to verify that it is running by hitting port 5000 with a web
 browser and getting a 404 error:
 
-``` console
+```ShellSession
 $ curl localhost:5000
 404 page not found
 ```
@@ -229,7 +219,7 @@ $ curl localhost:5000
 To use an image hosted by this registry, simply say this in your `Pod`'s
 `spec.containers[].image` field:
 
-``` yaml
+```yaml
     image: localhost:5000/user/container
 ```
 
@@ -241,7 +231,7 @@ building locally and want to push to your cluster.
 You can use `kubectl` to set up a port-forward from your local node to a
 running Pod:
 
-``` console
+```ShellSession
 $ POD=$(kubectl get pods --namespace kube-system -l k8s-app=registry \
             -o template --template '{{range .items}}{{.metadata.name}} {{.status.phase}}{{"\n"}}{{end}}' \
             | grep Running | head -1 | cut -f1 -d' ')

docs/setting-up-your-first-cluster.md

@@ -252,11 +252,7 @@ Ansible will now execute the playbook, this can take up to 20 minutes.
 We will leverage a kubeconfig file from one of the controller nodes to access
  the cluster as administrator from our local workstation.
 
-> In this simplified set-up, we did not include a load balancer that usually
+> In this simplified set-up, we did not include a load balancer that usually sits on top of the three controller nodes for a high available API server endpoint. In this simplified tutorial we connect directly to one of the three controllers.
- sits on top of the
-three controller nodes for a high available API server endpoint. In this
- simplified tutorial we connect directly to one of the three
- controllers.
 
 First, we need to edit the permission of the kubeconfig file on one of the
 controller nodes:

docs/vagrant.md

@@ -58,7 +58,7 @@ see [download documentation](/docs/downloads.md).
 
 The following is an example of setting up and running kubespray using `vagrant`.
 For repeated runs, you could save the script to a file in the root of the
-kubespray and run it by executing 'source <name_of_the_file>.
+kubespray and run it by executing `source <name_of_the_file>`.
 
 ```ShellSession
 # use virtualenv to install all python requirements

docs/vars.md

@@ -81,7 +81,7 @@ following default cluster parameters:
   raise an assertion in playbooks if the `kubelet_max_pods` var also isn't adjusted accordingly
   (assertion not applicable to calico which doesn't use this as a hard limit, see
   [Calico IP block sizes](https://docs.projectcalico.org/reference/resources/ippool#block-sizes).
-  
+
 * *enable_dual_stack_networks* - Setting this to true will provision both IPv4 and IPv6 networking for pods and services.
 
 * *kube_service_addresses_ipv6* - Subnet for cluster IPv6 IPs (default is ``fd85:ee78:d8a6:8607::1000/116``). Must not overlap with ``kube_pods_subnet_ipv6``.
@@ -99,7 +99,7 @@ following default cluster parameters:
 
 * *coredns_k8s_external_zone* - Zone that will be used when CoreDNS k8s_external plugin is enabled
   (default is k8s_external.local)
-  
+
 * *enable_coredns_k8s_endpoint_pod_names* - If enabled, it configures endpoint_pod_names option for kubernetes plugin.
   on the CoreDNS service.