+.. SPDX-FileCopyrightText: 2021 Anuket contributors
+..
+.. SPDX-License-Identifier: CC-BY-4.0
+
===================================
Welcome to Kuberef's documentation!
===================================
implementation according to CNTT RA-2 in close collaboration with the
CNTT RI-2 workstream.
-The entire implementation is divided into two stages - Host provisioning
-and Kubernetes provisioning.
-
-This guide describes how to get started with a potential RI-2 deployment
-using `Cloud Infra Automation Framework <https://docs.nordix.org/submodules/infra/engine/docs/user-guide.html#framework-user-guide>`_
-for the Host provisioning stage and Intel's `BMRA <https://github.com/intel/container-experience-kits>`_
-for the Kubernetes provisioning stage.
-
.. note::
This is just an example of a possible RI-2 deployment. Kuberef aims to
Infrastructure Prerequisites
=============================
-You need one physical server acting as a jump server along with minimum of two additional
-servers on which RI-2 will be deployed. Please refer to Chapter 3 in CNTT RI-2 Documentation
+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>`_
for detailed information on the server and network specifications.
-Additionally, please make sure that you have KVM installed and set up on your jump server. This
-is needed because the deployment will spin up a VM which will then carry out the host and
-Kubernetes installation.
+Additionally, please make note of the following:
-Deployment
-=============================
+1. Ensure that you have KVM installed and set up on your jump server. This is needed
+ because the deployment will spin up a VM which will then carry out the host and
+ Kubernetes installation.
-Before initiating the deployment, please note the following:
+2. Generate SSH keypair.
-1. Add your configuration templates, ``pdf.yaml`` and ``idf.yaml`` under ``hw_config/<vendor>``.
+3. Add user to the sudo and libvirt group and have passwordless sudo enabled.
-2. Modify the environmental variables defined in ``deploy.env`` to match your setup.
+4. Install Ansible (tested with 2.9.14) and yq.
-3. Update ``hw_config/<vendor>/setup_network.sh`` with your correct networking info. This particular
- script sets up networking on the provisioned nodes after the host provisioning stage is successful.
+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.
-.. note::
+**Ubuntu 20.04 LTS**
+
+Install packages using Apt
+
+* ``apt-get install qemu-kvm libvirt-daemon-system libvirt-clients genisoimage virt-manager bridge-utils python3-libvirt git jq``
+* Some of the packages might be installed already
+* Start libvirtd if it isn't running using ``service libvirtd start``
+* Add user to libvirt group using ``adduser `id -un` libvirt``
+* Log out and in on the current user to update the groups
+
+If ``python`` isn't available in the path, consider adding a symlink for Python3
+
+* ``ln -s /usr/bin/python3 /usr/bin/python``
+
+Install Ansible
+
+* ``apt-add-repository --yes --update ppa:ansible/ansible``
+* ``apt-get install ansible``
+
+Install ``yq`` binary from Github
+
+* Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
+* Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
+
+You might need to update the libvirt (QEMU) configuration if there are problems with user and group
+
+* You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
+* If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
- Depending on your setup, this script might not be needed. #WIP
+Generate SSH keypair
-Once ready, issue the following command to initiate the deployment
+* ``ssh-keygen -t rsa -b 4096``
-.. code-block:: bash
+**CentOS 8**
- ./deploy.sh
+Install packages using dnf
+* ``dnf install qemu-kvm qemu-img libvirt virt-install libvirt-client python3 git jq``
+* Some of the packages might be installed already
+* Start libvirtd if it isn't running using ``service libvirtd restart``
+* Add user to libvirt group using ``usermod -a -G libvirt $(whoami)``
+* Log out and in on the current user to update the groups
+
+If ``python`` isn't available in the path, consider adding a symlink for Python3
+
+* ``ln -s /usr/bin/python3 /usr/bin/python``
+
+Install Ansible
+* ``dnf install epel-release``
+* ``dnf install ansible``
+
+Install ``yq`` binary from Github
+
+* Find the correct build of version `v3.4.1 <https://github.com/mikefarah/yq/releases/tag/3.4.1>`_
+* Place the binary in ``/usr/bin/yq`` and make it executable ``chmod +x /usr/bin/yq``
+
+You might need to update the libvirt (QEMU) configuration if there are problems with user and group
+
+* You can set the user and group to "root" by uncommenting `user` and `group` in ``/etc/libvirt/qemu.conf``
+* If the configuration is changed, finish by restarting libvirtd through ``service libvirtd restart``
+
+Generate SSH keypair
+
+* ``ssh-keygen -t rsa -b 4096``
+
+Deployment
+=============================
+
+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>`_
+for instructions to get started with the deployment.
Once the deployment is successful, you will have a fully functional RI-2 setup!
+
+Validation of the Reference Implementation
+===========================================
+
+Kuberef has been validated by running test cases defined in CNTT RC2 Cookbook.
+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>`_.
Code Review / kuberef.git / blobdiff