aboutsummaryrefslogtreecommitdiffstats
path: root/docs/usecases/contiv/Vagrant.rst
diff options
context:
space:
mode:
authorNathan Skrzypczak <nathan.skrzypczak@gmail.com>2021-08-19 11:38:06 +0200
committerDave Wallace <dwallacelf@gmail.com>2021-10-13 23:22:32 +0000
commit9ad39c026c8a3c945a7003c4aa4f5cb1d4c80160 (patch)
tree3cca19635417e28ae381d67ae31c75df2925032d /docs/usecases/contiv/Vagrant.rst
parentf47122e07e1ecd0151902a3cabe46c60a99bee8e (diff)
docs: better docs, mv doxygen to sphinx
This patch refactors the VPP sphinx docs in order to make it easier to consume for external readers as well as VPP developers. It also makes sphinx the single source of documentation, which simplifies maintenance and operation. Most important updates are: - reformat the existing documentation as rst - split RELEASE.md and move it into separate rst files - remove section 'events' - remove section 'archive' - remove section 'related projects' - remove section 'feature by release' - remove section 'Various links' - make (Configuration reference, CLI docs, developer docs) top level items in the list - move 'Use Cases' as part of 'About VPP' - move 'Troubleshooting' as part of 'Getting Started' - move test framework docs into 'Developer Documentation' - add a 'Contributing' section for gerrit, docs and other contributer related infos - deprecate doxygen and test-docs targets - redirect the "make doxygen" target to "make docs" Type: refactor Change-Id: I552a5645d5b7964d547f99b1336e2ac24e7c209f Signed-off-by: Nathan Skrzypczak <nathan.skrzypczak@gmail.com> Signed-off-by: Andrew Yourtchenko <ayourtch@gmail.com>
Diffstat (limited to 'docs/usecases/contiv/Vagrant.rst')
-rw-r--r--docs/usecases/contiv/Vagrant.rst284
1 files changed, 284 insertions, 0 deletions
diff --git a/docs/usecases/contiv/Vagrant.rst b/docs/usecases/contiv/Vagrant.rst
new file mode 100644
index 00000000000..035dd09b88e
--- /dev/null
+++ b/docs/usecases/contiv/Vagrant.rst
@@ -0,0 +1,284 @@
+Contiv-VPP Vagrant Installation
+===============================
+
+Prerequisites
+-------------
+
+The following items are prerequisites before installing vagrant: -
+Vagrant 2.0.1 or later - Hypervisors: - VirtualBox 5.2.8 or later -
+VMWare Fusion 10.1.0 or later or VmWare Workstation 14 - For VmWare
+Fusion, you will need the `Vagrant VmWare Fusion
+plugin <https://www.vagrantup.com/vmware/index.html>`__ - Laptop or
+server with at least 4 CPU cores and 16 Gig of RAM
+
+Creating / Shutting Down / Destroying the Cluster
+-------------------------------------------------
+
+This folder contains the Vagrant file that is used to create a single or
+multi-node Kubernetes cluster using Contiv-VPP as a Network Plugin.
+
+The folder is organized into two subfolders:
+
+- (config) - contains the files that share cluster information, which
+ are used during the provisioning stage (master IP address,
+ Certificates, hash-keys). **CAUTION:** Editing is not recommended!
+- (vagrant) - contains scripts that are used for creating, destroying,
+ rebooting and shutting down the VMs that host the K8s cluster.
+
+To create and run a K8s cluster with a *contiv-vpp CNI* plugin, run the
+``vagrant-start`` script, located in the `vagrant
+folder <https://github.com/contiv/vpp/tree/master/vagrant>`__. The
+``vagrant-start`` script prompts the user to select the number of worker
+nodes for the kubernetes cluster. Zero (0) worker nodes mean that a
+single-node cluster (with one kubernetes master node) will be deployed.
+
+Next, the user is prompted to select either the *production environment*
+or the *development environment*. Instructions on how to build the
+development *contiv/vpp-vswitch* image can be found below in the
+`development
+environment <#building-and-deploying-the-dev-contiv-vswitch-image>`__
+command section.
+
+The last option asks the user to select either *Without StealTheNIC* or
+*With StealTheNIC*. Using option *With StealTheNIC* has the plugin
+“steal” interfaces owned by Linux and uses their configuration in VPP.
+
+For the production environment, enter the following commands:
+
+::
+
+ | => ./vagrant-start
+ Please provide the number of workers for the Kubernetes cluster (0-50) or enter [Q/q] to exit: 1
+
+ Please choose Kubernetes environment:
+ 1) Production
+ 2) Development
+ 3) Quit
+ --> 1
+ You chose Development environment
+
+ Please choose deployment scenario:
+ 1) Without StealTheNIC
+ 2) With StealTheNIC
+ 3) Quit
+ --> 1
+ You chose deployment without StealTheNIC
+
+ Creating a production environment, without STN and 1 worker node(s)
+
+For the development environment, enter the following commands:
+
+::
+
+ | => ./vagrant-start
+ Please provide the number of workers for the Kubernetes cluster (0-50) or enter [Q/q] to exit: 1
+
+ Please choose Kubernetes environment:
+ 1) Production
+ 2) Development
+ 3) Quit
+ --> 2
+ You chose Development environment
+
+ Please choose deployment scenario:
+ 1) Without StealTheNIC
+ 2) With StealTheNIC
+ 3) Quit
+ --> 1
+ You chose deployment without StealTheNIC
+
+ Creating a development environment, without STN and 1 worker node(s)
+
+To destroy and clean-up the cluster, run the *vagrant-cleanup* script,
+located `inside the vagrant
+folder <https://github.com/contiv/vpp/tree/master/vagrant>`__:
+
+::
+
+ cd vagrant/
+ ./vagrant-cleanup
+
+To shutdown the cluster, run the *vagrant-shutdown* script, located
+`inside the vagrant
+folder <https://github.com/contiv/vpp/tree/master/vagrant>`__:
+
+::
+
+ cd vagrant/
+ ./vagrant-shutdown
+
+- To reboot the cluster, run the *vagrant-reload* script, located
+ `inside the vagrant
+ folder <https://github.com/contiv/vpp/tree/master/vagrant>`__:
+
+::
+
+ cd vagrant/
+ ./vagrant-reload
+
+- From a suspended state, or after a reboot of the host machine, the
+ cluster can be brought up by running the *vagrant-up* script.
+
+Building and Deploying the dev-contiv-vswitch Image
+---------------------------------------------------
+
+If you chose the optional development-environment-deployment option,
+then perform the following instructions on how to build a modified
+*contivvpp/vswitch* image:
+
+- Make sure changes in the code have been saved. From the k8s-master
+ node, build the new *contivvpp/vswitch* image (run as sudo):
+
+::
+
+ vagrant ssh k8s-master
+ cd /vagrant/config
+ sudo ./save-dev-image
+
+- The newly built *contivvpp/vswitch* image is now tagged as *latest*.
+ Verify the build with ``sudo docker images``; the *contivvpp/vswitch*
+ should have been created a few seconds ago. The new image with all
+ the changes must become available to all the nodes in the K8s
+ cluster. To make the changes available to all, load the docker image
+ into the running worker nodes (run as sudo):
+
+::
+
+ vagrant ssh k8s-worker1
+ cd /vagrant/config
+ sudo ./load-dev-image
+
+- Verify with ``sudo docker images``; the old *contivvpp/vswitch*
+ should now be tagged as ``<none>`` and the latest tagged
+ *contivvpp/vswitch* should have been created a few seconds ago.
+
+Exploring the Cluster
+---------------------
+
+Once the cluster is up, perform the following steps: - Log into the
+master:
+
+::
+
+ cd vagrant
+
+ vagrant ssh k8s-master
+
+ Welcome to Ubuntu 16.04 LTS (GNU/Linux 4.4.0-21-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com/
+ vagrant@k8s-master:~$
+
+- Verify the Kubernetes/Contiv-VPP installation. First, verify the
+ nodes in the cluster:
+
+::
+
+ vagrant@k8s-master:~$ kubectl get nodes -o wide
+
+ NAME STATUS ROLES AGE VERSION EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
+ k8s-master Ready master 22m v1.9.2 <none> Ubuntu 16.04 LTS 4.4.0-21-generic docker://17.12.0-ce
+ k8s-worker1 Ready <none> 15m v1.9.2 <none> Ubuntu 16.04 LTS 4.4.0-21-generic docker://17.12.0-ce
+
+- Next, verify that all pods are running correctly:
+
+::
+
+ vagrant@k8s-master:~$ kubectl get pods -n kube-system -o wide
+
+ NAME READY STATUS RESTARTS AGE IP NODE
+ contiv-etcd-2ngdc 1/1 Running 0 17m 192.169.1.10 k8s-master
+ contiv-ksr-x7gsq 1/1 Running 3 17m 192.169.1.10 k8s-master
+ contiv-vswitch-9bql6 2/2 Running 0 17m 192.169.1.10 k8s-master
+ contiv-vswitch-hpt2x 2/2 Running 0 10m 192.169.1.11 k8s-worker1
+ etcd-k8s-master 1/1 Running 0 16m 192.169.1.10 k8s-master
+ kube-apiserver-k8s-master 1/1 Running 0 16m 192.169.1.10 k8s-master
+ kube-controller-manager-k8s-master 1/1 Running 0 15m 192.169.1.10 k8s-master
+ kube-dns-6f4fd4bdf-62rv4 2/3 CrashLoopBackOff 14 17m 10.1.1.2 k8s-master
+ kube-proxy-bvr74 1/1 Running 0 10m 192.169.1.11 k8s-worker1
+ kube-proxy-v4fzq 1/1 Running 0 17m 192.169.1.10 k8s-master
+ kube-scheduler-k8s-master 1/1 Running 0 16m 192.169.1.10 k8s-master
+
+- If you want your pods to be scheduled on both the master and the
+ workers, you have to untaint the master node:
+
+::
+
+- Check VPP and its interfaces:
+
+::
+
+ vagrant@k8s-master:~$ sudo vppctl
+ _______ _ _ _____ ___
+ __/ __/ _ \ (_)__ | | / / _ \/ _ \
+ _/ _// // / / / _ \ | |/ / ___/ ___/
+ /_/ /____(_)_/\___/ |___/_/ /_/
+
+ vpp# sh interface
+ Name Idx State Counter Count
+ GigabitEthernet0/8/0 1 up rx packets 14
+ rx bytes 3906
+ tx packets 18
+ tx bytes 2128
+ drops 3
+ ip4 13
+ ...
+
+
+- Make sure that ``GigabitEthernet0/8/0`` is listed and that its status
+ is ``up``.
+
+- Next, create an example deployment of nginx pods:
+
+::
+
+ vagrant@k8s-master:~$ kubectl run nginx --image=nginx --replicas=2
+ deployment "nginx" created
+
+- Check the status of the deployment:
+
+::
+
+ vagrant@k8s-master:~$ kubectl get deploy -o wide
+
+ NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE CONTAINERS IMAGES SELECTOR
+ nginx 2 2 2 2 2h nginx nginx run=nginx
+
+- Verify that the pods in the deployment are up and running:
+
+::
+
+ vagrant@k8s-master:~$ kubectl get pods -o wide
+
+ NAME READY STATUS RESTARTS AGE IP NODE
+ nginx-8586cf59-6kx2m 1/1 Running 1 1h 10.1.2.3 k8s-worker1
+ nginx-8586cf59-j5vf9 1/1 Running 1 1h 10.1.2.2 k8s-worker1
+
+- Issue an HTTP GET request to a pod in the deployment:
+
+::
+
+ vagrant@k8s-master:~$ wget 10.1.2.2
+
+ --2018-01-19 12:34:08-- http://10.1.2.2/
+ Connecting to 10.1.2.2:80... connected.
+ HTTP request sent, awaiting response... 200 OK
+ Length: 612 [text/html]
+ Saving to: ‘index.html.1’
+
+ index.html.1 100%[=========================================>] 612 --.-KB/s in 0s
+
+ 2018-01-19 12:34:08 (1.78 MB/s) - ‘index.html.1’ saved [612/612]
+
+How to SSH into k8s Worker Node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To SSH into k8s Worker Node, perform the following steps:
+
+::
+
+ cd vagrant
+
+ vagrant status
+
+ vagrant ssh k8s-worker1