1 .. SPDX-FileCopyrightText: 2021 Anuket contributors
3 .. SPDX-License-Identifier: CC-BY-4.0
5 ===================================
6 Welcome to Kuberef's documentation!
7 ===================================
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.
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>`_.
22 Infrastructure Prerequisites
23 =============================
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.
28 Additionally, please make note of the following:
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.
34 2. Generate SSH keypair.
36 3. Add user to the sudo and libvirt group and have passwordless sudo enabled.
38 4. Install Ansible (tested with 2.9.14), yq (v3.4.1), jq and virtual-env.
40 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.
44 Install packages using Apt
46 * ``apt-get install qemu-kvm libvirt-daemon-system libvirt-clients genisoimage virt-manager bridge-utils python3-libvirt git jq``
47 * Some of the packages might be installed already
48 * Start libvirtd if it isn't running using ``service libvirtd start``
49 * Add user to libvirt group using ``adduser `id -un` libvirt``
50 * Log out and in on the current user to update the groups
52 If ``python`` isn't available in the path, consider adding a symlink for Python3
54 * ``ln -s /usr/bin/python3 /usr/bin/python``
58 * ``apt-add-repository --yes --update ppa:ansible/ansible``
59 * ``apt-get install ansible``
61 Install ``yq`` binary from Github
63 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
64 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
66 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
68 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
69 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
73 * ``ssh-keygen -t rsa -b 4096``
77 Install packages using dnf
79 * ``dnf install qemu-kvm qemu-img libvirt virt-install libvirt-client python3 git jq``
80 * Some of the packages might be installed already
81 * Start libvirtd if it isn't running using ``service libvirtd restart``
82 * Add user to libvirt group using ``usermod -a -G libvirt $(whoami)``
83 * Log out and in on the current user to update the groups
85 If ``python`` isn't available in the path, consider adding a symlink for Python3
87 * ``ln -s /usr/bin/python3 /usr/bin/python``
90 * ``dnf install epel-release``
91 * ``dnf install ansible``
93 Install ``yq`` binary from Github
95 * Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
96 * Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
98 You might need to update the libvirt (QEMU) configuration if there are problems with user and group
100 * You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
101 * If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
105 * ``ssh-keygen -t rsa -b 4096``
107 Deployment on Baremetal and Provider Infrastructure
108 ===================================================
110 Please refer to Chapter 4 of `Anuket RI-2 Documentation <https://cntt.readthedocs.io/en/latest/ref_impl/cntt-ri2/chapters/chapter04.html>`_
111 for instructions to get started with the deployment.
113 Deployment on Virtualized Infrastructure
114 ========================================
116 Following are the steps to spin up a minimalistic Kuberef deployment on VMs aimed for development and testing use-cases:
118 * Set ``VENDOR=libvirt-vms``, ``DISTRO=ubuntu1804`` in ``deploy.env``. Additionally, ensure that other environmental variables defined in this file match your setup.
119 * 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.
120 * Once ready, initiate the deployment by running ``dev/deploy_on_vms.sh`.
122 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``.
124 Verify that all services in the VM's are running by ``kubectl get all --all-namespaces``.
126 Note that this feature is currently only supported on Ubuntu 18.04. For other OS, additional configuration might be needed.
128 Validation of the Reference Implementation
129 ===========================================
131 Kuberef is validated by running test cases defined in Anuket RC-2 Cookbook.
132 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>`_.