docs/release/installation/deployment-guide.rst

   1 ===================================
   2 Welcome to Kuberef's documentation!
   3 ===================================
   4
   5 Introduction
   6 ============
   7
   8 Kuberef aims to develop and deliver a Kubernetes-based reference
   9 implementation according to CNTT RA-2 in close collaboration with the
  10 CNTT RI-2 workstream.
  11
  12 .. note::
  13
  14     This is just an example of a possible RI-2 deployment. Kuberef aims to
  15     support and include other potential hardware and Kubernetes deployers as well. More
  16     details can be found in the `Kuberef Wiki <https://wiki.opnfv.org/spaces/viewspace.action?key=KUB>`_.
  17
  18 Infrastructure Prerequisites
  19 =============================
  20
  21 Please refer to Chapter 3 of `CNTT RI-2 Documentation <https://github.com/cntt-n/CNTT/blob/master/doc/ref_impl/cntt-ri2/chapters/chapter03.md>`_
  22 for detailed information on the server and network specifications.
  23
  24 Additionally, please make note of the following:
  25
  26 1. Ensure that you have KVM installed and set up on your jump server. This is needed
  27    because the deployment will spin up a VM which will then carry out the host and
  28    Kubernetes installation.
  29
  30 2. Generate SSH keypair.
  31
  32 3. Add user to the sudo and libvirt group and have passwordless sudo enabled.
  33
  34 4. Install Ansible (tested with 2.9.14) and yq.
  35
  36 Installing and configuring the prerequisites will depend on the operating system installed on the jump server. Below are additional details for setting up some of the more popular distributions.
  37
  38 **Ubuntu 20.04 LTS**
  39
  40 Install packages using Apt
  41
  42 * ``apt-get install qemu-kvm libvirt-daemon-system libvirt-clients genisoimage virt-manager bridge-utils python3-libvirt git jq``
  43 * Some of the packages might be installed already
  44 * Start libvirtd if it isn't running using ``service libvirtd start``
  45 * Add user to libvirt group using ``adduser `id -un` libvirt``
  46 * Log out and in on the current user to update the groups
  47
  48 If ``python`` isn't available in the path, consider adding a symlink for Python3
  49
  50 * ``ln -s /usr/bin/python3 /usr/bin/python``
  51
  52 Install Ansible
  53
  54 * ``apt-add-repository --yes --update ppa:ansible/ansible``
  55 * ``apt-get install ansible``
  56
  57 Install ``yq`` binary from Github
  58
  59 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
  60 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
  61
  62 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
  63
  64 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
  65 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
  66
  67 Generate SSH keypair
  68
  69 * ``ssh-keygen -t rsa -b 4096``
  70
  71 **CentOS 8**
  72
  73 Install packages using dnf
  74
  75 * ``dnf install qemu-kvm qemu-img libvirt virt-install libvirt-client python3 git jq``
  76 * Some of the packages might be installed already
  77 * Start libvirtd if it isn't running using ``service libvirtd restart``
  78 * Add user to libvirt group using ``usermod -a -G libvirt $(whoami)``
  79 * Log out and in on the current user to update the groups
  80
  81 If ``python`` isn't available in the path, consider adding a symlink for Python3
  82
  83 * ``ln -s /usr/bin/python3 /usr/bin/python``
  84
  85 Install Ansible
  86 * ``dnf install epel-release``
  87 * ``dnf install ansible``
  88
  89 Install ``yq`` binary from Github
  90
  91 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
  92 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
  93
  94 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
  95
  96 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
  97 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
  98
  99 Generate SSH keypair
 100
 101 * ``ssh-keygen -t rsa -b 4096``
 102
 103 Deployment
 104 =============================
 105
 106 Please refer to Chapter 4 of `CNTT RI-2 Documentation <https://github.com/cntt-n/CNTT/blob/master/doc/ref_impl/cntt-ri2/chapters/chapter04.md>`_
 107 for instructions to get started with the deployment.
 108
 109 Once the deployment is successful, you will have a fully functional RI-2 setup!
 110
 111 Validation of the Reference Implementation
 112 ===========================================
 113
 114 Kuberef has been validated by running test cases defined in CNTT RC2 Cookbook.
 115 For setting up RC2 Conformance toolchain, please refer to `CNTT RC-2 Chapter 03 <https://github.com/cntt-n/CNTT/blob/master/doc/ref_cert/RC2/chapters/chapter03.md>`_.