Skip to content

Prerequisites

The following packages are required:

  • CONDA: is an open source package management system. It enables users of Windows, macOS, or Linux, to create, save, load, and switch between software environments on your computer.
  • Igw-py is the python environment custumed for igwn.
  • Helm 3 helps to manage Kubernetes applications. It allow to create and manage packages named helm chart (i.e. a .yaml file) that can be installed inside kubernetes containers fulfilling the requisites and maintaning the coherence.
  • OpenSSL
  • ensure to have a read_api scoped personal acces active. This can be obtained from [ligo-git]{https://git.ligo.org/} under Preferences->Access Tokens->Add new token indicating in Select scopes the option read_api.
  • download llai-deploy-sandboxed git folder on destination host and use it as working directory. (hereafter commands are supposed to be executed from this folder)
  • k3s K3s is a fully conformant production-ready Kubernetes distribution. how to install k3s is reported here

Warning

Before to start ensure that docker, Kubectl and minikube are not installed on the system. Their presence may create some conflicts: commands here reported may not work properly.

k3s installation

Warning

One should note that kubectl is installed automatically during the K3s installation. If for some reason this was installed before, k3s is not able to link kubectl command to its own version, thus kubectl commands operating to k3s cluster should be executed as k3s kubectl.

To install k3s simply executes

curl -sfL https://get.k3s.io | sh -
The command uses curl to download the script located at k3s web site and executes the script by piping it to sh -. Upon script execution, K3s cluster installation will begin with the default configuration options which creates a single-node Kubernetes cluster.

After running this installation:

  • The K3s service will be configured to automatically restart after node reboots or if the process crashes or is killed
  • Additional utilities will be installed, including kubectl, crictl, ctr, k3s-killall.sh, and k3s-uninstall.sh
  • A kubeconfig file will be written to /etc/rancher/k3s/k3s.yaml and the kubectl installed by K3s will automatically use it.

A single-node server installation is a fully-functional Kubernetes cluster, including all the datastore, control-plane, kubelet, and container runtime components necessary to host workload pods. It is not necessary to add additional server or agents nodes, but you may want to do so to add additional capacity or redundancy to your cluster.

to verify that all work smooth do

systemctl status k3s # check the status of k3s service
sudo kubectl get pods -A # see what pod are already running "out of the box"
sudo kubectl get all -n kube-system # check the default Kubernetes objects deployed after the installation of K3s

output example of out-of-thebox pods active in a new deployes k3s intallation
$ sudo kubectl get pods -A
NAMESPACE     NAME                                      READY   STATUS      RESTARTS   AGE
kube-system   coredns-576bfc4dc7-wbfqd                  1/1     Running     0          77s
kube-system   helm-install-traefik-crd-zb8m4            0/1     Completed   0          77s
kube-system   helm-install-traefik-m98l4                0/1     Completed   1          77s
kube-system   local-path-provisioner-6795b5f9d8-bj7wr   1/1     Running     0          77s
kube-system   metrics-server-557ff575fb-xqwgm           1/1     Running     0          77s
kube-system   svclb-traefik-5201ba89-7qbcs              2/2     Running     0          65s
kube-system   traefik-5fb479b77-kpcc2                   1/1     Running     0          65s

$ sudo kubectl get all -n kube-system 
NAME                                          READY   STATUS      RESTARTS   AGE
pod/coredns-576bfc4dc7-vz7bd                  1/1     Running     0          56s
pod/helm-install-traefik-crd-czcfj            0/1     Completed   0          56s
pod/helm-install-traefik-nc95c                0/1     Completed   1          56s
pod/local-path-provisioner-6795b5f9d8-clpbc   1/1     Running     0          56s
pod/metrics-server-557ff575fb-m9lmg           1/1     Running     0          56s
pod/svclb-traefik-7d627134-xfw64              2/2     Running     0          44s
pod/traefik-5fb479b77-ql87h                   1/1     Running     0          44s

NAME                     TYPE           CLUSTER-IP      EXTERNAL-IP       PORT(S)                      AGE
service/kube-dns         ClusterIP      10.43.0.10      <none>            53/UDP,53/TCP,9153/TCP       68s
service/metrics-server   ClusterIP      10.43.132.113   <none>            443/TCP                      66s
service/traefik          LoadBalancer   10.43.253.250   XXX.XXX.XXX.XXX   80:32015/TCP,443:31559/TCP   44s

NAME                                    DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
daemonset.apps/svclb-traefik-7d627134   1         1         1       1            1           <none>          44s

NAME                                     READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/coredns                  1/1     1            1           68s
deployment.apps/local-path-provisioner   1/1     1            1           67s
deployment.apps/metrics-server           1/1     1            1           67s
deployment.apps/traefik                  1/1     1            1           44s

NAME                                                DESIRED   CURRENT   READY   AGE
replicaset.apps/coredns-576bfc4dc7                  1         1         1       56s
replicaset.apps/local-path-provisioner-6795b5f9d8   1         1         1       56s
replicaset.apps/metrics-server-557ff575fb           1         1         1       56s
replicaset.apps/traefik-5fb479b77                   1         1         1       44s

NAME                                 STATUS     COMPLETIONS   DURATION   AGE
job.batch/helm-install-traefik       Complete   1/1           17s        65s
job.batch/helm-install-traefik-crd   Complete   1/1           14s        65s
where XXX.XXX.XXX.XXX is the local IP address of the host machine.

Allowing user to operate on k3s cluster

By default it is needed to be a superuser to operate command on k3s cluster. This was set for security reason. To allow an non-administrator account to operate on cluster file k3s.yaml file should be copied on a local folder and its permission modified to be accessible by the selected user. Then the KUBECONFIG environmental variable must be set to redirect program like helm to operate this k3s istance.

The following lines create a hidden folder inside home directory where k3s.yaml file is copied and made visible by user <username>.

pushd ~
mkdir .kube
cd .kube/
sudo /etc/rancher/k3s/k3s.yaml .
sudo cp /etc/rancher/k3s/k3s.yaml .
export KUBECONFIG='/home/<username>/.kube/k3s.yaml'
sudo chown <username>:<usergroup> k3s.yaml 
popd

KUBECONFIG must be set before activating the cluster or, as alternative, defined inside .bashrc file.

note that missing this configuration part may cause a connection refused error:

Error: Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp 127.0.0.1:8080: connect: connection refused

alternative methods

In general, to avoid to use sudo command to operate on k3s, is sufficient to modify permission access to k3s.yaml file:

sudo chmod 644 /etc/rancher/k3s/k3s.yaml
This command set the permission of the configuration files as readable by all users, this may cause some security warning afterwards (the alternative is to add your user to the same group of k3s.yaml file). Please note that after k3s restart, the file come back to original permission flags.

To proper address kubernetes and helm command to operate on k3s cluster, there are two options

a) Leverage the KUBECONFIG environment variable:

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

b) specify the location of the kubeconfig file in the command:

helm --kubeconfig /etc/rancher/k3s/k3s.yaml ls --all-namespaces
for additional access configurations (e.g. Accessing the Cluster from Outside with kubectl) see k3s Cluster Access

Closing k3s cluster

It is important to know that k3s service is separated from the cluster itself, so it may occour that k3s service may be stopped by means of systemctl stop k3s but pods are still running and using resources. To proper stop the cluster and free the resources execute che command:

/usr/local/bin/k3s-killall.sh

k3s unistall

You must run a shell script called ‘/usr/local/bin/k3s-uninstall.sh’ to uninstall K3S. The script is generated automatically upon K3s installation and can be used to execute a full cleanup. During the uninstallation, any K3s configuration and cluster tools that were created or installed during the K3s installation are deleted.

Execute the following command to uninstall K3s:

/usr/local/bin/k3s-uninstall.sh