Installing KUMA on a Kubernetes cluster from scratch

Distributed installation of KUMA involves multiple steps:

1. Verifying that the hardware, software, and installation requirements for KUMA are satisfied.
2. Preparing the test machine.

   The test machine is used during the program installation process: the installer files are unpacked and run on it.

3. Preparing the target machines.

   The program components are installed on the target machines.

4. Preparing the k0s.inventory.yml inventory file.

   Create an inventory file with a description of the network structure of program components. The installer uses this inventory file to deploy KUMA.

5. Installing the program.

   Install the program and log in to the web interface.

6. Creating services.

   Create the client part of the services in the KUMA web interface and install the server part of the services on the target machines.

   Make sure the KUMA installation is complete before you install KUMA services. We recommend installing services in the following order: storage, collectors, correlators, and agents.

   When deploying several KUMA services on the same host, you must specify unique ports for each service using the --api.port <port> parameters during installation.

If necessary, you use your company's certificate as the KUMA web console certificate.

Preparing the test machine

To prepare the test machine for the KUMA installation:

1. Ensure that hardware, software, and installation requirements of the program are met.
2. Generate an SSH key for authentication on the SSH servers of the target machines by executing the following command:

   sudo ssh-keygen -f /root/.ssh/id_rsa -N "" -C kuma-ansible-installer

   If SSH root access is blocked on the test machine, generate an SSH key for authentication on the SSH servers of the target machines using a user from the sudo group:

   If the user does not have sudo rights, add the user to the sudo group:

   usermod -aG sudo user

   sudo ssh-keygen -f /home/<name of the user from sudo group>/.ssh/id_rsa -N "" -C kuma-ansible-installer

   As a result, the key is generated and saved in the user's home directory. You should specify the full path to the key in the inventory file in the value of the ansible_ssh_private_key_file parameter so that the key is available during installation.

3. Make sure that the test machine has network access to all the target machines by host name and copy the SSH key to each target machine by carrying out the following command:

   sudo ssh-copy-id -i /root/.ssh/id_rsa root@<host name of the test machine>

   If SSH root access is blocked on the test machine and you want to use the SSH key from the home directory of the sudo group user, make sure that the test machine has network access to all target machines by host name and copy the SSH key to each target machine using the following command:

   sudo ssh-copy-id -i /home/<name of a user in the sudo group>/.ssh/id_rsa root@<host name of the test machine>

4. Copy the kuma-ansible-installer-ha-<version number> .tar.gz installer archive to the test machine and unpack it using the following command:

   sudo tar -xpf kuma-ansible-installer-ha-<version number>.tar.gz

The test machine is ready for the KUMA installation.

Preparing the target machine

To prepare the target machine for the installation of KUMA components:

1. Ensure that hardware, software, and installation requirements are met.
2. Specify the host name. We recommend specifying the FQDN. For example, kuma1.example.com.

   You should not change the KUMA host name after installation: this will make it impossible to verify the authenticity of certificates and will disrupt the network communication between the program components.

3. Register the target machine in your organization's DNS zone to allow host names to be translated to IP addresses.

   The option of using the /etc/hosts file is not available when the Core is deployed in Kubernetes.

4. To get the hostname that you must specify when installing KUMA, run the following command and record the result:

   hostname -f

   The test machine must be able to access the target machine using this name.

The target machine is ready for the installation of KUMA components.

Preparing the k0s.inventory.yml inventory file

To create the k0s.inventory.yml inventory file:

1. Go to the KUMA installer folder by executing the following command:

   cd kuma-ansible-installer-ha

2. Copy the k0s.inventory.yml.template file to create the expand.inventory.yml inventory file:

   cp k0s.inventory.yml.template k0s.inventory.yml

3. Edit the inventory file settings in k0s.inventory.yml.

   Sample inventory file for a demo installation with the Core in Kubernetes

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: false

   generate_etc_hosts: false

   airgap: true

   deploy_example_services: true

   kuma:

   children:

   kuma_core:

   hosts:

   kuma.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma.example.com:

   kuma_correlator:

   hosts:

   kuma.example.com:

   kuma_storage:

   hosts:

   kuma.example.com:

   shard: 1

   replica: 1

   keeper: 1

   kuma_k0s:

   children:

   kuma_control_plane_master_worker:

   hosts:

   kuma-cpw.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   For a demo installation, specify deploy_example_services: true. KUMA will deploy demo services on the specified hosts and assign the shard, replica, and keeper roles to the specified host; configuring these roles in the KUMA web interface is not necessary for a demo installation.

   Sample inventory file for a distributed installation in a high availability configuration with 3 controllers, 2 worker nodes, and 1 balancer

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: false

   generate_etc_hosts: false

   airgap: true

   deploy_example_services: false

   kuma:

   children:

   kuma_core:

   hosts:

   kuma-core.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma-collector.example.com:

   kuma_correlator:

   hosts:

   kuma-correlator.example.com:

   kuma_storage:

   hosts:

   kuma-storage-cluster1.server1.example.com

   kuma-storage-cluster1.server2.example.com

   kuma-storage-cluster1.server3.example.com

   kuma-storage-cluster1.server4.example.com

   kuma-storage-cluster1.server5.example.com

   kuma-storage-cluster1.server6.example.com

   kuma-storage-cluster1.server7.example.com

   kuma_k0s:

   children:

   kuma_lb:

   hosts:

   kuma-lb.example.com:

   kuma_managed_lb: true

   kuma_control_plane_master:

   hosts:

   kuma_cpm.example.com:

   ansible_host: 10.0.1.10

   kuma_control_plane_master_worker:

   kuma_control_plane:

   hosts:

   kuma_cp2.example.com:

   ansible_host: 10.0.1.11

   kuma_cp3.example.com:

   ansible_host: 10.0.1.12

   kuma_control_plane_worker:

   kuma_worker:

   hosts:

   kuma-w1.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   kuma-w2.example.com:

   ansible_host: 10.0.2.12

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   For such a configuration, specify the need_transfer: false, airgap: true, deploy_example_services: false, and in the kuma_storage section, list the servers for the storage cluster. After the installation is complete, you can use the KUMA web interface to assign the shard, replica and keeper roles to the servers specified in the inventory.

   Sample inventory file for migrating the Core from a distributed installation to a Kubernetes cluster to ensure high availability

   all:

   vars:

   ansible_connection: ssh

   ansible_user: root

   deploy_to_k8s: true

   need_transfer: true

   generate_etc_hosts: false

   airgap: true

   deploy_example_services: false

   kuma:

   children:

   kuma_core:

   hosts:

   kuma-core.example.com:

   mongo_log_archives_number: 14

   mongo_log_frequency_rotation: daily

   mongo_log_file_size: 1G

   kuma_collector:

   hosts:

   kuma-collector.example.com:

   kuma_correlator:

   hosts:

   kuma-correlator.example.com:

   kuma_storage:

   hosts:

   kuma-storage-cluster1.server1.example.com

   kuma-storage-cluster1.server2.example.com

   kuma-storage-cluster1.server3.example.com

   kuma-storage-cluster1.server4.example.com

   kuma-storage-cluster1.server5.example.com

   kuma-storage-cluster1.server6.example.com

   kuma-storage-cluster1.server7.example.com

   kuma_k0s:

   children:

   kuma_lb:

   hosts:

   kuma-lb.example.com:

   kuma_managed_lb: true

   kuma_control_plane_master:

   hosts:

   kuma_cpm.example.com:

   ansible_host: 10.0.1.10

   kuma_control_plane_master_worker:

   kuma_control_plane:

   hosts:

   kuma_cp2.example.com:

   ansible_host: 10.0.1.11

   kuma_cp3.example.com:

   ansible_host: 10.0.1.12

   kuma_control_plane_worker:

   kuma_worker:

   hosts:

   kuma-w1.example.com:

   ansible_host: 10.0.2.11

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   kuma-w2.example.com:

   ansible_host: 10.0.2.12

   extra_args: "--labels=kaspersky.com/kuma-core=true,kaspersky.com/kuma-ingress=true,node.longhorn.io/create-default-disk=true"

   The kuma_core, kuma_ collector, kuma_correlator, kuma_storage sections of your k0s.inventory.yml inventory file must contain the same hosts that were used in the distributed.inventory.yml file when KUMA was upgraded from version 2.1.3 to version 3.0.2 or when a new installation was performed. In the k0s.inventory.yml inventory file, set deploy_to_k8s: true, need_transfer: true, airgap: true, deploy_example_services: false.

We recommend backing up the inventory file that you used to install the program. You can use it to add components to the system or remove KUMA.

Installing the program in a high availability configuration

KUMA is installed using the Ansible tool and the YML inventory file. The installation is performed using the test machine, where all of the KUMA components are installed on the target machines.

To install KUMA:

1. On the test machine, open the folder containing the unpacked installer.

   cd kuma-ansible-installer-ha

2. Place the license key file in the <installer directory>/roles/kuma/files/ directory.

   The key file must be named license.key.

3. Run the installer from the folder with the unpacked installer:

   sudo ./install.sh k0s.inventory.yml

4. Accept the terms of the End User License Agreement.

   If you do not accept the terms of the End User License Agreement, the program will not be installed.

KUMA components are installed. The screen will display the URL of the KUMA web interface and the user name and password that must be used to access the web interface.

By default, the KUMA web interface address is https://<FQDN or IP address of the core component>:7220.

Default login credentials (after the first login, you must change the password of the admin account):
- user name — admin
- password— mustB3Ch@ng3d!

We recommend backing up the inventory file that you used to install the program. You can use it to add components to the system or remove KUMA.