docs/release/installation/deployment-guide.rst

   1 .. SPDX-FileCopyrightText: 2021 Anuket contributors
   2 ..
   3 .. SPDX-License-Identifier: CC-BY-4.0
   4
   5 ===================================
   6 Welcome to Kuberef's documentation!
   7 ===================================
   8
   9 Introduction
  10 ============
  11
  12 Kuberef aims to develop and deliver a Kubernetes-based reference
  13 implementation according to Anuket RA-2 in close collaboration with the
  14 Anuket RI-2 workstream.
  15
  16 .. note::
  17
  18     This is just an example of a possible RI-2 deployment. Kuberef aims to
  19     support and include other potential hardware and Kubernetes deployers as well. More
  20     details can be found in the `Kuberef Wiki <https://wiki.anuket.io/display/HOME/Kuberef>`_.
  21
  22 Infrastructure Prerequisites
  23 =============================
  24
  25 Please refer to Chapter 3 of `Anuket RI-2 Documentation <https://cntt.readthedocs.io/en/latest/ref_impl/cntt-ri2/chapters/chapter03.html>`_
  26 for detailed information on the server and network specifications.
  27
  28 Additionally, please make note of the following:
  29
  30 1. Ensure that you have KVM installed and set up on your jump server. This is needed
  31    because the deployment will spin up a VM which will then carry out the host and
  32    Kubernetes installation.
  33
  34 2. A non-root user and generate SSH keypair.
  35
  36 3. Add user to the sudo and libvirt group and have passwordless sudo enabled.
  37
  38 4. Install Python3 (tested with 3.6.9), Ansible (tested with 2.9.14), Docker, yq (v3.4.1), git, jq and virtual-env (16.2 or later).
  39
  40 Installing and configuring the prerequisites will depend on the operating system installed on the jump server.
  41 Below are additional details for setting up some of the more popular distributions.
  42
  43 **Ubuntu 20.04 LTS**
  44
  45 .. note::
  46
  47     Please use Ubuntu 18.04 instead when deploying on virtualized infrastructure.
  48     Otherwise, you will get an error "E: Package 'libvirt-bin' has no installation candidate".
  49     This is because that openstack ironic will install package libvirt-bin which
  50     has been split into libvirt-daemon-system and libvirt-clients from Ubuntu 18.10.
  51     It works on Ubuntu 20.04 when deploying on baremetal and provider infrastructure because
  52     they create a jumphost VM with Ubuntu 18.04 to do the ironic steps in it.
  53
  54 Install packages using Apt
  55
  56 * ``sudo apt-get install -y qemu-kvm libvirt-daemon-system libvirt-clients libvirt-dev genisoimage virt-manager bridge-utils python3-libvirt git jq``
  57 * Some of the packages might be installed already
  58 * Start libvirtd if it isn't running using ``sudo service libvirtd start``
  59 * Add user to libvirt group using ``sudo adduser `id -un` libvirt``
  60 * Log out and in on the current user to update the groups
  61
  62 If ``python`` isn't available in the path, consider adding a symlink for Python3
  63
  64 * ``ln -s /usr/bin/python3 /usr/bin/python``
  65
  66 Install Ansible
  67
  68 * ``apt-add-repository --yes --update ppa:ansible/ansible``
  69 * ``apt-get install ansible``
  70
  71 Install Docker
  72
  73 * Follow the official doc `Install Docker Engine <https://docs.docker.com/engine/install/>`_
  74
  75 Install ``yq`` binary from Github
  76
  77 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
  78 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
  79
  80 Install virtual-env
  81
  82 * ``pip install --upgrade virtualenv``
  83
  84 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
  85
  86 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
  87 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
  88
  89 Generate SSH keypair
  90
  91 * ``ssh-keygen -t rsa -b 4096``
  92
  93 **CentOS 8**
  94
  95 Install packages using dnf
  96
  97 * ``dnf install qemu-kvm qemu-img libvirt virt-install libvirt-client python3 git jq``
  98 * Some of the packages might be installed already
  99 * Start libvirtd if it isn't running using ``service libvirtd restart``
 100 * Add user to libvirt group using ``usermod -a -G libvirt $(whoami)``
 101 * Log out and in on the current user to update the groups
 102
 103 If ``python`` isn't available in the path, consider adding a symlink for Python3
 104
 105 * ``ln -s /usr/bin/python3 /usr/bin/python``
 106
 107 Install Ansible
 108 * ``dnf install epel-release``
 109 * ``dnf install ansible``
 110
 111 Install ``yq`` binary from Github
 112
 113 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
 114 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
 115
 116 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
 117
 118 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
 119 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
 120
 121 Generate SSH keypair
 122
 123 * ``ssh-keygen -t rsa -b 4096``
 124
 125 Deployment on Baremetal and Provider Infrastructure
 126 ===================================================
 127
 128 Please refer to Chapter 4 of `Anuket RI-2 Documentation <https://cntt.readthedocs.io/en/latest/ref_impl/cntt-ri2/chapters/chapter04.html>`_
 129 for instructions to get started with the deployment.
 130
 131 Deployment on Virtualized Infrastructure
 132 ========================================
 133
 134 Following are the steps to spin up a minimalistic Kuberef deployment on VMs aimed for development and testing use-cases:
 135
 136 * Get kuberef code from gerrit ``git clone "https://gerrit.opnfv.org/gerrit/kuberef"``.
 137 * Set ``VENDOR=libvirt-vms``, ``DISTRO=ubuntu1804`` in ``deploy.env``. Additionally, ensure that other environmental variables defined in this file match your setup.
 138 * The hardware and network configurations for the VMs are defined under ``hw_config/libvirt-vms``. Currently, the configuration for one master and one worker VM is defined, but additional VM's can be added as desired. Additionally, the default values of hardware storage, CPU information, etc. can be adapted as per need.
 139 * Once ready, initiate the deployment by running ``dev/deploy_on_vms.sh``.
 140
 141 After the successful completion of the deployment, you can do ``virsh list`` to list the provisioned VM's and connect to them over SSH using user ``root``. The SSH public key of the user is already added by the installer in the VM's. The IP of the VMs can be found under ``hw_config/libvirt-vms/pdf.yaml``.
 142
 143 Verify that all services in the VM's are running by ``kubectl get all --all-namespaces``.
 144
 145 Note that this feature is currently only supported on Ubuntu 18.04. For other OS, additional configuration might be needed.
 146
 147 Validation of the Reference Implementation
 148 ===========================================
 149
 150 Kuberef is validated by running test cases defined in Anuket RC-2 Cookbook.
 151 For setting up RC-2 Conformance toolchain, please refer to `Anuket RC-2 Chapter 03 <https://cntt.readthedocs.io/en/latest/ref_cert/RC2/chapters/chapter03.html>`_.