XTesting/kubespray/docs/vagrant.md

   1 # Vagrant
   2
   3 Assuming you have Vagrant 2.0+ installed with virtualbox, libvirt/qemu or
   4 vmware, but is untested) you should be able to launch a 3 node Kubernetes
   5 cluster by simply running `vagrant up`.
   6
   7 This will spin up 3 VMs and install kubernetes on them.
   8 Once they are completed you can connect to any of them by running `vagrant ssh k8s-[1..3]`.
   9
  10 To give an estimate of the expected duration of a provisioning run:
  11 On a dual core i5-6300u laptop with an SSD, provisioning takes around 13
  12 to 15 minutes, once the container images and other files are cached.
  13 Note that libvirt/qemu is recommended over virtualbox as it is quite a bit
  14 faster, especially during boot-up time.
  15
  16 For proper performance a minimum of 12GB RAM is recommended.
  17 It is possible to run a 3 node cluster on a laptop with 8GB of RAM using
  18 the default Vagrantfile, provided you have 8GB zram swap configured and
  19 not much more than a browser and a mail client running.
  20 If you decide to run on such a machine, then also make sure that any tmpfs
  21 devices, that are mounted, are mostly empty and disable any swapfiles
  22 mounted on HDD/SSD or you will be in for some serious swap-madness.
  23 Things can get a bit sluggish during provisioning, but when that's done,
  24 the system will actually be able to perform quite well.
  25
  26 ## Customize Vagrant
  27
  28 You can override the default settings in the `Vagrantfile` either by
  29 directly modifying the `Vagrantfile` or through an override file.
  30 In the same directory as the `Vagrantfile`, create a folder called
  31 `vagrant` and create `config.rb` file in it.
  32 An example of how to configure this file is given below.
  33
  34 ## Use alternative OS for Vagrant
  35
  36 By default, Vagrant uses Ubuntu 18.04 box to provision a local cluster.
  37 You may use an alternative supported operating system for your local cluster.
  38
  39 Customize `$os` variable in `Vagrantfile` or as override, e.g.,:
  40
  41 ```ShellSession
  42 echo '$os = "flatcar-stable"' >> vagrant/config.rb
  43 ```
  44
  45 The supported operating systems for vagrant are defined in the `SUPPORTED_OS`
  46 constant in the `Vagrantfile`.
  47
  48 ## File and image caching
  49
  50 Kubespray can take quite a while to start on a laptop. To improve provisioning
  51 speed, the variable 'download_run_once' is set. This will make kubespray
  52 download all files and containers just once and then redistributes them to
  53 the other nodes and as a bonus, also cache all downloads locally and re-use
  54 them on the next provisioning run. For more information on download settings
  55 see [download documentation](/docs/downloads.md).
  56
  57 ## Example use of Vagrant
  58
  59 The following is an example of setting up and running kubespray using `vagrant`.
  60 For repeated runs, you could save the script to a file in the root of the
  61 kubespray and run it by executing 'source <name_of_the_file>.
  62
  63 ```ShellSession
  64 # use virtualenv to install all python requirements
  65 VENVDIR=venv
  66 virtualenv --python=/usr/bin/python3.7 $VENVDIR
  67 source $VENVDIR/bin/activate
  68 pip install -r requirements.txt
  69
  70 # prepare an inventory to test with
  71 INV=inventory/my_lab
  72 rm -rf ${INV}.bak &> /dev/null
  73 mv ${INV} ${INV}.bak &> /dev/null
  74 cp -a inventory/sample ${INV}
  75 rm -f ${INV}/hosts.ini
  76
  77 # customize the vagrant environment
  78 mkdir vagrant
  79 cat << EOF > vagrant/config.rb
  80 \$instance_name_prefix = "kub"
  81 \$vm_cpus = 1
  82 \$num_instances = 3
  83 \$os = "centos-bento"
  84 \$subnet = "10.0.20"
  85 \$network_plugin = "flannel"
  86 \$inventory = "$INV"
  87 \$shared_folders = { 'temp/docker_rpms' => "/var/cache/yum/x86_64/7/docker-ce/packages" }
  88 EOF
  89
  90 # make the rpm cache
  91 mkdir -p temp/docker_rpms
  92
  93 vagrant up
  94
  95 # make a copy of the downloaded docker rpm, to speed up the next provisioning run
  96 scp kub-1:/var/cache/yum/x86_64/7/docker-ce/packages/* temp/docker_rpms/
  97
  98 # copy kubectl access configuration in place
  99 mkdir $HOME/.kube/ &> /dev/null
 100 ln -s $PWD/$INV/artifacts/admin.conf $HOME/.kube/config
 101 # make the kubectl binary available
 102 sudo ln -s $PWD/$INV/artifacts/kubectl /usr/local/bin/kubectl
 103 #or
 104 export PATH=$PATH:$PWD/$INV/artifacts
 105 ```
 106
 107 If a vagrant run failed and you've made some changes to fix the issue causing
 108 the fail, here is how you would re-run ansible:
 109
 110 ```ShellSession
 111 ansible-playbook -vvv -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory cluster.yml
 112 ```
 113
 114 If all went well, you check if it's all working as expected:
 115
 116 ```ShellSession
 117 kubectl get nodes
 118 ```
 119
 120 The output should look like this:
 121
 122 ```ShellSession
 123 $ kubectl get nodes
 124 NAME    STATUS   ROLES                  AGE     VERSION
 125 kub-1   Ready    control-plane,master   4m37s   v1.22.5
 126 kub-2   Ready    control-plane,master   4m7s    v1.22.5
 127 kub-3   Ready    <none>                 3m7s    v1.22.5
 128 ```
 129
 130 Another nice test is the following:
 131
 132 ```ShellSession
 133 kubectl get pods --all-namespaces -o wide
 134 ```
 135
 136 Which should yield something like the following:
 137
 138 ```ShellSession
 139 $ kubectl get pods --all-namespaces -o wide
 140 NAMESPACE            NAME                                      READY   STATUS    RESTARTS   AGE     IP            NODE    NOMINATED NODE   READINESS GATES
 141 kube-system          coredns-8474476ff8-m2469                  1/1     Running   0          2m45s   10.233.65.2   kub-2   <none>           <none>
 142 kube-system          coredns-8474476ff8-v5wzj                  1/1     Running   0          2m41s   10.233.64.3   kub-1   <none>           <none>
 143 kube-system          dns-autoscaler-5ffdc7f89d-76tnv           1/1     Running   0          2m43s   10.233.64.2   kub-1   <none>           <none>
 144 kube-system          kube-apiserver-kub-1                      1/1     Running   1          4m54s   10.0.20.101   kub-1   <none>           <none>
 145 kube-system          kube-apiserver-kub-2                      1/1     Running   1          4m33s   10.0.20.102   kub-2   <none>           <none>
 146 kube-system          kube-controller-manager-kub-1             1/1     Running   1          5m1s    10.0.20.101   kub-1   <none>           <none>
 147 kube-system          kube-controller-manager-kub-2             1/1     Running   1          4m33s   10.0.20.102   kub-2   <none>           <none>
 148 kube-system          kube-flannel-9xgf5                        1/1     Running   0          3m10s   10.0.20.102   kub-2   <none>           <none>
 149 kube-system          kube-flannel-l8jbl                        1/1     Running   0          3m10s   10.0.20.101   kub-1   <none>           <none>
 150 kube-system          kube-flannel-zss4t                        1/1     Running   0          3m10s   10.0.20.103   kub-3   <none>           <none>
 151 kube-system          kube-multus-ds-amd64-bhpc9                1/1     Running   0          3m2s    10.0.20.103   kub-3   <none>           <none>
 152 kube-system          kube-multus-ds-amd64-n6vl8                1/1     Running   0          3m2s    10.0.20.102   kub-2   <none>           <none>
 153 kube-system          kube-multus-ds-amd64-qttgs                1/1     Running   0          3m2s    10.0.20.101   kub-1   <none>           <none>
 154 kube-system          kube-proxy-2x4jl                          1/1     Running   0          3m33s   10.0.20.101   kub-1   <none>           <none>
 155 kube-system          kube-proxy-d48r7                          1/1     Running   0          3m33s   10.0.20.103   kub-3   <none>           <none>
 156 kube-system          kube-proxy-f45lp                          1/1     Running   0          3m33s   10.0.20.102   kub-2   <none>           <none>
 157 kube-system          kube-scheduler-kub-1                      1/1     Running   1          4m54s   10.0.20.101   kub-1   <none>           <none>
 158 kube-system          kube-scheduler-kub-2                      1/1     Running   1          4m33s   10.0.20.102   kub-2   <none>           <none>
 159 kube-system          nginx-proxy-kub-3                         1/1     Running   0          3m33s   10.0.20.103   kub-3   <none>           <none>
 160 kube-system          nodelocaldns-cg9tz                        1/1     Running   0          2m41s   10.0.20.102   kub-2   <none>           <none>
 161 kube-system          nodelocaldns-htswt                        1/1     Running   0          2m41s   10.0.20.103   kub-3   <none>           <none>
 162 kube-system          nodelocaldns-nsp7s                        1/1     Running   0          2m41s   10.0.20.101   kub-1   <none>           <none>
 163 local-path-storage   local-path-provisioner-66df45bfdd-km4zg   1/1     Running   0          2m54s   10.233.66.2   kub-3   <none>           <none>
 164 ```