You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

129 lines
7.8 KiB

  1. Introduction
  2. ============
  3. Assuming you have Vagrant 2.0+ installed with virtualbox, libvirt/qemu or vmware, but is untested) you should be able to launch a 3 node Kubernetes cluster by simply running `vagrant up`. This will spin up 3 VMs and install kubernetes on them. Once they are completed you can connect to any of them by running `vagrant ssh k8s-[1..3]`.
  4. To give an estimate of the expected duration of a provisioning run: On a dual core i5-6300u laptop with an SSD, provisioning takes around 13 to 15 minutes, once the container images and other files are cached. Note that libvirt/qemu is recommended over virtualbox as it is quite a bit faster, especially during boot-up time.
  5. For proper performance a minimum of 12GB RAM is recommended. It is possible to run a 3 node cluster on a laptop with 8GB of RAM using the default Vagrantfile, provided you have 8GB zram swap configured and not much more than a browser and a mail client running. If you decide to run on such a machine, then also make sure that any tmpfs devices, that are mounted, are mostly empty and disable any swapfiles mounted on HDD/SSD or you will be in for some serious swap-madness. Things can get a bit sluggish during provisioning, but when that's done, the system will actually be able to perform quite well.
  6. Customize Vagrant
  7. =================
  8. 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.
  9. Use alternative OS for Vagrant
  10. ==============================
  11. By default, Vagrant uses Ubuntu 18.04 box to provision a local cluster. You may use an alternative supported operating system for your local cluster.
  12. Customize `$os` variable in `Vagrantfile` or as override, e.g.,:
  13. echo '$os = "coreos-stable"' >> vagrant/config.rb
  14. The supported operating systems for vagrant are defined in the `SUPPORTED_OS` constant in the `Vagrantfile`.
  15. File and image caching
  16. ======================
  17. Kubespray can take quite a while to start on a laptop. To improve provisioning speed, the variable 'download_run_once' is set. This will make kubespray download all files and containers just once and then redistributes them to the other nodes and as a bonus, also cache all downloads locally and re-use them on the next provisioning run. For more information on download settings see [download documentation](docs/downloads.md).
  18. Example use of Vagrant
  19. ======================
  20. 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>.
  21. ```
  22. # use virtualenv to install all python requirements
  23. VENVDIR=venv
  24. virtualenv --python=/usr/bin/python3.7 $VENVDIR
  25. source $VENVDIR/bin/activate
  26. pip install -r requirements.txt
  27. # prepare an inventory to test with
  28. INV=inventory/my_lab
  29. rm -rf ${INV}.bak &> /dev/null
  30. mv ${INV} ${INV}.bak &> /dev/null
  31. cp -a inventory/sample ${INV}
  32. rm -f ${INV}/hosts.ini
  33. # customize the vagrant environment
  34. mkdir vagrant
  35. cat << EOF > vagrant/config.rb
  36. \$instance_name_prefix = "kub"
  37. \$vm_cpus = 1
  38. \$num_instances = 3
  39. \$os = "centos-bento"
  40. \$subnet = "10.0.20"
  41. \$network_plugin = "flannel"
  42. \$inventory = "$INV"
  43. \$shared_folders = { 'temp/docker_rpms' => "/var/cache/yum/x86_64/7/docker-ce/packages" }
  44. EOF
  45. # make the rpm cache
  46. mkdir -p temp/docker_rpms
  47. vagrant up
  48. # make a copy of the downloaded docker rpm, to speed up the next provisioning run
  49. scp kub-1:/var/cache/yum/x86_64/7/docker-ce/packages/* temp/docker_rpms/
  50. # copy kubectl access configuration in place
  51. mkdir $HOME/.kube/ &> /dev/null
  52. ln -s $INV/artifacts/admin.conf $HOME/.kube/config
  53. # make the kubectl binary available
  54. sudo ln -s $INV/artifacts/kubectl /usr/local/bin/kubectl
  55. #or
  56. export PATH=$PATH:$INV/artifacts
  57. ```
  58. 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:
  59. ```
  60. ansible-playbook -vvv -i .vagrant/provisioners/ansible/inventory/vagrant_ansible_inventory cluster.yml
  61. ```
  62. If all went well, you check if it's all working as expected:
  63. ```
  64. kubectl get nodes
  65. ```
  66. The output should look like this:
  67. ```
  68. $ kubectl get nodes
  69. NAME STATUS ROLES AGE VERSION
  70. kub-1 Ready master 32m v1.14.1
  71. kub-2 Ready master 31m v1.14.1
  72. kub-3 Ready <none> 31m v1.14.1
  73. ```
  74. Another nice test is the following:
  75. ```
  76. kubectl get po --all-namespaces -o wide
  77. ```
  78. Which should yield something like the following:
  79. ```
  80. NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
  81. kube-system coredns-97c4b444f-9wm86 1/1 Running 0 31m 10.233.66.2 kub-3 <none> <none>
  82. kube-system coredns-97c4b444f-g7hqx 0/1 Pending 0 30m <none> <none> <none> <none>
  83. kube-system dns-autoscaler-5fc5fdbf6-5c48k 1/1 Running 0 31m 10.233.66.3 kub-3 <none> <none>
  84. kube-system kube-apiserver-kub-1 1/1 Running 0 32m 10.0.20.101 kub-1 <none> <none>
  85. kube-system kube-apiserver-kub-2 1/1 Running 0 32m 10.0.20.102 kub-2 <none> <none>
  86. kube-system kube-controller-manager-kub-1 1/1 Running 0 32m 10.0.20.101 kub-1 <none> <none>
  87. kube-system kube-controller-manager-kub-2 1/1 Running 0 32m 10.0.20.102 kub-2 <none> <none>
  88. kube-system kube-flannel-8tgcn 2/2 Running 0 31m 10.0.20.103 kub-3 <none> <none>
  89. kube-system kube-flannel-b2hgt 2/2 Running 0 31m 10.0.20.101 kub-1 <none> <none>
  90. kube-system kube-flannel-zx4bc 2/2 Running 0 31m 10.0.20.102 kub-2 <none> <none>
  91. kube-system kube-proxy-4bjdn 1/1 Running 0 31m 10.0.20.102 kub-2 <none> <none>
  92. kube-system kube-proxy-l5tt5 1/1 Running 0 31m 10.0.20.103 kub-3 <none> <none>
  93. kube-system kube-proxy-x59q8 1/1 Running 0 31m 10.0.20.101 kub-1 <none> <none>
  94. kube-system kube-scheduler-kub-1 1/1 Running 0 32m 10.0.20.101 kub-1 <none> <none>
  95. kube-system kube-scheduler-kub-2 1/1 Running 0 32m 10.0.20.102 kub-2 <none> <none>
  96. kube-system kubernetes-dashboard-6c7466966c-jqz42 1/1 Running 0 31m 10.233.66.4 kub-3 <none> <none>
  97. kube-system nginx-proxy-kub-3 1/1 Running 0 32m 10.0.20.103 kub-3 <none> <none>
  98. kube-system nodelocaldns-2x7vh 1/1 Running 0 31m 10.0.20.102 kub-2 <none> <none>
  99. kube-system nodelocaldns-fpvnz 1/1 Running 0 31m 10.0.20.103 kub-3 <none> <none>
  100. kube-system nodelocaldns-h2f42 1/1 Running 0 31m 10.0.20.101 kub-1 <none> <none>
  101. ```
  102. Create clusteradmin rbac and get the login token for the dashboard:
  103. ```
  104. kubectl create -f contrib/misc/clusteradmin-rbac.yml
  105. kubectl -n kube-system describe secret kubernetes-dashboard-token | grep 'token:' | grep -o '[^ ]\+$'
  106. ```
  107. Copy it to the clipboard and now log in to the [dashboard](https://10.0.20.101:6443/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#!/login).