From 4bf2d7a2c2bb71724696dea3adadb56c6bccd7e5 Mon Sep 17 00:00:00 2001
From: Max Gautier <mg@max.gautier.name>
Date: Thu, 12 Sep 2024 16:44:30 +0200
Subject: [PATCH] Rework vagrant documentation

- Use proper syntax highlighting for config.rb examples
- Consistent shell style ($ as prompt)
- Use only one way to do things
- Remove OS specific details
---
 docs/developers/vagrant.md | 87 +++++++++++++-------------------------
 1 file changed, 30 insertions(+), 57 deletions(-)

diff --git a/docs/developers/vagrant.md b/docs/developers/vagrant.md
index 83b5b999e..3fac58516 100644
--- a/docs/developers/vagrant.md
+++ b/docs/developers/vagrant.md
@@ -29,7 +29,26 @@ You can override the default settings in the `Vagrantfile` either by
 directly modifying the `Vagrantfile` or through an override file.
 In the same directory as the `Vagrantfile`, create a folder called
 `vagrant` and create `config.rb` file in it.
-An example of how to configure this file is given below.
+
+Example:
+
+```ruby
+# vagrant/config.rb
+$instance_name_prefix = "kub"
+$vm_cpus = 1
+$num_instances = 3
+$os = "centos8-bento"
+$subnet = "10.0.20"
+$network_plugin = "flannel"
+
+$extra_vars = {
+    dns_domain: my.custom.domain
+}
+# or
+$extra_vars = "path/to/extra/vars/file.yml"
+```
+
+For all available options look at the Vagrantfile (search for "CONFIG")
 
 ## Use alternative OS for Vagrant
 
@@ -57,73 +76,33 @@ see [download documentation](/docs/advanced/downloads.md).
 ## Example use of Vagrant
 
 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>`.
+Customize your settings as shown, above, then run the commands:
 
 ```ShellSession
 # use virtualenv to install all python requirements
 VENVDIR=venv
-virtualenv --python=/usr/bin/python3.7 $VENVDIR
-source $VENVDIR/bin/activate
-pip install -r requirements.txt
+$ virtualenv --python=/usr/bin/python3.7 $VENVDIR
+$ source $VENVDIR/bin/activate
+$ pip install -r requirements.txt
 
-# prepare an inventory to test with
-INV=inventory/my_lab
-rm -rf ${INV}.bak &> /dev/null
-mv ${INV} ${INV}.bak &> /dev/null
-cp -a inventory/sample ${INV}
-rm -f ${INV}/hosts.ini
+$ vagrant up
 
-# customize the vagrant environment
-mkdir vagrant
-cat << EOF > vagrant/config.rb
-\$instance_name_prefix = "kub"
-\$vm_cpus = 1
-\$num_instances = 3
-\$os = "centos8-bento"
-\$subnet = "10.0.20"
-\$network_plugin = "flannel"
-\$inventory = "$INV"
-\$shared_folders = { 'temp/docker_rpms' => "/var/cache/yum/x86_64/7/docker-ce/packages" }
-\$extra_vars = {
-    dns_domain: my.custom.domain
-}
-# or
-\$extra_vars = "path/to/extra/vars/file.yml"
-EOF
-
-# make the rpm cache
-mkdir -p temp/docker_rpms
-
-vagrant up
-
-# make a copy of the downloaded docker rpm, to speed up the next provisioning run
-scp kub-1:/var/cache/yum/x86_64/7/docker-ce/packages/* temp/docker_rpms/
-
-# copy kubectl access configuration in place
-mkdir $HOME/.kube/ &> /dev/null
-ln -s $PWD/$INV/artifacts/admin.conf $HOME/.kube/config
+# Access the cluster
+$ export INV=.vagrant/provisionners/ansible/inventory
+$ export KUBECONFIG=${INV}/artifacts/admin.conf
 # make the kubectl binary available
-sudo ln -s $PWD/$INV/artifacts/kubectl /usr/local/bin/kubectl
-#or
-export PATH=$PATH:$PWD/$INV/artifacts
+$ export PATH=$PATH:$PWD/$INV/artifacts
 ```
 
 If a vagrant run failed and you've made some changes to fix the issue causing
 the fail, here is how you would re-run ansible:
 
 ```ShellSession
-ansible-playbook -vvv -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory cluster.yml
+vagrant provision
 ```
 
 If all went well, you check if it's all working as expected:
 
-```ShellSession
-kubectl get nodes
-```
-
-The output should look like this:
-
 ```ShellSession
 $ kubectl get nodes
 NAME    STATUS   ROLES                  AGE     VERSION
@@ -134,12 +113,6 @@ kub-3   Ready    <none>                 3m7s    v1.22.5
 
 Another nice test is the following:
 
-```ShellSession
-kubectl get pods --all-namespaces -o wide
-```
-
-Which should yield something like the following:
-
 ```ShellSession
 $ kubectl get pods --all-namespaces -o wide
 NAMESPACE            NAME                                      READY   STATUS    RESTARTS   AGE     IP            NODE    NOMINATED NODE   READINESS GATES