How to Install KubeSphere on Ubuntu 22.04

Kubesphere free and open-source Kubernetes platform and cloud-native application management verified by CNCF. It's an enterprise-grade Kubernetes container platform with feature-rich and tailored for hybrid multi-cloud deployment. By default, Kubesphere includes full-stack automated IT operations and is streamlined with DevOps workflows. It can be deployed to an existing Kubernetes cluster or Linux distributions, or also you can set up your Kubernetes with Kubesphere included via KubeKey, a command-line tool for Linux for deploying, updating, and scaling Kubernetes cluster automatically.

Kubesphere provides an intuitive graphical web UI for managing the Kubernetes cluster. it's also come with pluggable CI/CD tools like jenkins that allows you to set up automatically CI/CD pipeline. It also provides Source-to-Image (S2I) for the automated building of reproducible container images from source code, and Binary-to-Image (B2I) for building reproducible container images from a binary file (Jar, War, Binary file).

This artcile will guide through deploying the Kubernetes and Kubesphere on Ubuntu 22.04 servers. You will using multiple Ubuntu servers for this deployment, and you will be using the KubeKey application that provided by Kubesphere for automatic deployment of Kubernetes cluster and Kubesphere.

Prerequisites

To fllow and complete this tutorial, you will need the following requirements:

  • Three Linux servers running ubuntu 22.04 - You will be using one server as the Kubernetes control-plane and two servers as worker nodes.
  • A non-root user with sudo/root administrator pirivlges.

Setup Hosts and User

Before installing Kubernetes and Kubesphere, you must set up the '/etc/hosts' file and create a new user with sudo password-less on all of your servers. So be sure to run the following commands on all of your Ubuntu servers.

Now open the file '/etc/hosts' using the following nano editor command.

sudo nano /etc/hosts

Add details of server IP addresses and hostname to the file.

192.168.5.35    master    master
192.168.5.121   node1     node1
192.168.5.122   node2     node2

Save the file, and close the editor when finished.

Next, enter the following command to create a new user called 'ubuntu' and set up the password for the new user 'ubuntu'. When prompted, input your password and repeat.

sudo useradd -m -s /bin/bash ubuntu
sudo passwd ubuntu

Lastly, run the following command to allow the 'ubuntu' user to execute 'sudo' without a password. The 'ubuntu' user here will be used for installing package dependencies, so you must ensure the user can become root without a password.

cat <<EOF | sudo tee /etc/sudoers.d/ubuntu
Defaults:ubuntu !fqdn
Defaults:ubuntu !requiretty
ubuntu ALL=(ALL) NOPASSWD: ALL
EOF

After configuring the '/etc/hosts' file and creating the 'ubuntu' user, next you will set up the password-less SSH authentication for the user 'ubuntu'.

setup hosts users

Setting Up SSH Key-Based Authentication

In this section, you will be setting up a password-less SSH authentication for the user 'ubuntu'. So the scenario for installing Kubernetes and Kubesphre is from the 'master' server. And the installation to both 'node1' and 'node2' will be done automatically.

On the 'master' server, enter the following command to log in as user 'ubuntu'. then generate a new SSH key pair using the 'ssh-keygen' command as below. When finished, your SSH public and private keys will be stored in the '~/.ssh' directory.

su - ubuntu
ssh-keygen -t ed25519

generate ssh key

Next, enter the following command to the SSH public key from the 'master' server to all nodes that will be used for the Kubernetes and Kubesphre installation.

ssh-copy-id ubuntu@master
ssh-copy-id ubuntu@node1
ssh-copy-id ubuntu@node2

Input 'yes' to accept the SSH fingerprint for the server, then input the password for user 'ubuntu' when prompted. Once the SSH key is added, you should get an output such as 'Number of key(s) added: 1'.

Below is an output when adding the SSH public key to the localhost of the 'master' server.

upload ssh key to localhost

Below is an output when adding the SSH public key to the 'node1' server.

upload ssh key to node1

Below is an output when adding the SSH public key to the 'node2' server.

upload ssh key to node2

After the SSH public key is added and uploaded, you can now connect to all of your servers via the 'ubuntu' user without password authentication.

In the next section, you will verify and ensure that you can connect to all nodes/servers via a password-less 'ubuntu' user, then install some package dependencies.

Installing Dependencies

So, you have uploaded the SSH public key from the 'master' server to both the 'node1' and 'node2' servers. Now you will ensure that you can connect to both servers via 'ubuntu' user with SSH password-less authentication and install basic dependencies for Kubernetes and Kubesphere.

On the 'master' server, enter the following command to update and refresh your Ubuntu package index and install some package dependencies via the 'apt install' command below.

sudo apt update
sudo apt install curl socat conntrack ebtables ipset

ssh-keyscan -H master >> ~/.ssh/known_hosts

When prompted, input y to confirm and press ENTER to proceed.

install dependencies

Next, connect to the 'node1' server via the 'ssh' command below. After the command is executed, you should be logged in to 'node1' without password authentication.

ssh ubuntu@node1

Now enter the following apt command to update and refresh your Ubuntu package index. Then, install some basic package dependencies. Input y when prompted and press ENTER to proceed.

sudo apt update
sudo apt install curl socat conntrack ebtables ipset

login node1 install packages

Lastly, connect to the 'node2' server via the 'ssh' command below.

ssh ubuntu@node2

Once connected, enter the following command to update the repository package index. Then, install some package dependencies via the 'apt install' command.

sudo apt update
sudo apt install curl socat conntrack ebtables ipset

Input y when prompted and press ENTER to proceed.

login node2 install dependencies

At this point, you've configured your servers for the Kubernetes and Kubesphre installation. In the next section, you will download the binary file of KubeKey that will be used to initialize the Kubernetes cluster and install Kubesphere.

Downloading KubeKey on Master Node

In this section, you will download the KubeKey binary file to the 'master' server. The KubeKey is a single binary file that allows you to deploy the Kubernetes cluster, and/or with the KubeSphere administration dashboard. It also supports cloud-native add-ons, multi-node, and HA (High Availability).

Enter the following command to download the binary file of KubeKey to your current working directory. When the process is finished, you should see the file 'kk' in your directory.

curl -sfL https://get-kk.kubesphere.io | VERSION=v3.0.2 sh -

Now run the following command to make the file 'kk' executable.

chmod +x kk

download kubekey

Then, execute the binary file 'kk' to verify the current version and the list's available parameters on the KubeKey.

./kk version
./kk help

Below is a similar output that will be printed out on your terminal screen.

verify kubekey

After KubeKey is downloaded, you will next start the configuration of Kubernetes and Kubesphere deployment via KubeKey.

Create Kubernetes and Kubesphere Deployment Configuration

The KubeKey can be used to deploy the Kubernetes-only deployment or with the KubeSphere. It also supports both single Kubernetes deployment and multi-node deployments.

As for multi-node Kubernetes and Kubesphre deployment, you need to generate a YAML script that will define the server's configuration.

Execute the following 'kk' command to generate a new YAML configuration. In this example, you will generate a new YAML script 'deployment-kubesphre.yml' and specify the Kubernetes version to v1.24.2 and the Kubesphere v3.3.1.

./kk create config -f deployment-kubesphre.yml --with-kubernetes v1.24.2 --with-kubesphere v3.3.1

You should see an output such as 'Generate KubeKey config file successfully'.

generate kubekey configuration

Now open the YAML file 'deployment-kubesphre.yml' using the following nano editor command.

nano deployment-kubesphre.yml

Change the cluster name in the parameter 'metadata: testdeployment', and change the detail host's IP address, user, and private key for logging to the target servers. Lastly, on the 'roleGroup', specify which host that will be used as the control plane and worker nodes.

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: testdeployment
spec:
  hosts:
  - {name: master, address: 192.168.5.35, internalAddress: 192.168.5.35, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  - {name: node1, address: 192.168.5.121, internalAddress: 192.168.5.121, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  - {name: node2, address: 192.168.5.122, internalAddress: 192.168.5.122, user: ubuntu, privateKeyPath: "~/.ssh/id_ed25519"}
  roleGroups:
    etcd:
    - master
    control-plane:
    - master
    worker:
    - node1
    - node2

Save the file and exit the editor when finished.

hosts settings

As for this example, you will create a new Kubernetes cluster called 'testdeployment' with three different Ubuntu servers.

  • master as the etcd and control plane.
  • node1 and node2 will be used as worker nodes.

To install all requirements to the target servers, you will be using SSH and logging in with the private key '~/.ssh/id_ed25519' as a user 'ubuntu'. This user is configured as the password-less in visudo.

After generating and configuring the YAML file and building the Kubernetes and Kubesphre deployment, move to the following steps to start the deployment.

Deploying Kubernetes and Kubesphere

In this section, you will deploy both Kubernetes and Kubesphre with multi-node architecture via KubeKey and the YAML script 'deployment-kubesphre.yml'.

Execute the Kubekey 'kk' binary file below to start the Kubernetes and Kubesphere deployment with the YAML file 'deployment-kubesphre.yml'.

./kk create cluster -f deployment-kubesphre.yml

First, KubeKey will check the details requirements for the Kubernetes installation. When successful, you will be prompted to confirm the installation. Input yes and press ENTER to proceed.

deploying kubernetes kubepshere

This will take time like 5-10 minutes for the deployment to complete. When finished, you should see an output similar to this printed out on your terminal. Also, you will get the default admin user and password that can be used to log in to Kubesphere.

kubernetes deployment finished

Now open your web browser and visit the 'master' server IP address followed by port '30880' (i.e: http://192.168.5.35:30880/). You should see the Kubepshre login page.

Type the user as 'admin' and the default password 'P@88w0rd', then click Log In.

login page

After logging in, you should be asked to change the default password for the Kubepshre user 'admin'. Input your new password and click Submit.

change pass

When finished, you should see the Kubesphere administration dashboard. On the dashboard page, you should get the current version of Kubesphere v3.3.1 and the available Kubernetes cluster is 1.

kubesphere dashboard

Next, click on the Platform menu on the top left, then select Cluster Management.

cluster management

Below is the detail of the Kubernetes cluster that you have installed with multiple Ubuntu servers, the server 'master', node1, and node2.

default cluster

Now click on the Nodes menu to get detailed information on available nodes on the Kubernetes cluster. Below you can see there are three different nodes on the Kubernetes cluster. The 'master' server is used as both the control plane and worker node.

list nodes

Now click on the System Components to get the details of installed components on your Kubernetes and Kubesphere deployment. You can see theree diffwerent categroeis of components, the Kubesphere, Kubernetes, and Monitoring.

list components

Next, back to the terminal session of the 'master' server and run the following 'kubectl' command below to get the list of available nodes on your Kubernetes cluster.

kubectl get nodes

You should receive an output similar to this - There are three nodes available on the Kubernetes cluster, the master node that is used as the control plane, and the node1 and node2 that are used as worker nodes.

verify nodes

Enter the following command to get details information about each node on the Kubernetes cluster.

kubectl describe node

Below you can see the detail of the Kubernetes control plane on the 'master' server.

describe node master

Below is the detail of the worker node on the node1 server.

describe node1

Below is the detail of the worker node on the node2 server.

describe node2

Lastly, enter the following command to get the list of pods that running on your Kubernetes cluster.

kubectl get pods --all-namespaces

In the following output, you can see multiple namespaces 'kube-system', 'kubesphere-system', 'kubesphere-control-system', and 'kubesphere-monitoring-system' that are available on your Kubernetes cluster with all pods is running.

check pods

At this point, you have now deployed the Kubernetes cluster and Kubesphere with multiple Ubuntu server nodes. You have also accessed the Kubesphere administration dashboard and changed the default admin password.

With this in mind, you can now deploy your application to Kubernetes and Kubesphere. In the next step, you will deploy the simple Nginx web server to Kubernetes to ensure that your Kubernetes and Kubesphere installation is successful.

Deploying Pods to Kubernetes and Kubesphere

In this example, you will be deploying Nginx pods to the Kubernetes cluster and Kubesphere.

Run the following command to create a new deployment for the Nginx web server. In this example, we will create new Nginx Pods based on the image "nginx:alpine" with two replicas.

kubectl create deployment nginx --image=nginx:alpine --replicas=2

Now create a new service type "NodePort" that will expose the Nginx deployment using the following kubectl command. This command will create a new Kubernetes service named "nginx" with the type "NodePort" and expose the port "80" for the Pod.

kubectl create service nodeport nginx --tcp=80:80

create deployment service

Next, run the following kubectl command to check the list of the running pod on your Kubernetes cluster. And you should see two Nginx pods running.

kubectl get pods

check pods

Now check the list of available services on Kubernetes using the following command. You should see the "nginx" service type NodePort exposed the port "80" and port "32241" on Kubernetes hosts. The service NodePort will always expose the port between the range xxx-xxxx on Kubernetes hosts (worker nodes).

kubectl get svc

check services

Run the curl command below to access your Nginx deployment.

curl 10.233.14.102
curl node1:32241
curl node2:32241

Below is an output of the Nginx pod index.html page that is exposed on the 'master' server.

verify nginx deployment

Below is the output of the index.html source code from the "node1".

nginx index node1

And below is the index.html code from "node2".

nginx deployment master

Now back to the Kubesphere administration dashboard. Click on the Application Workloads, then click Workloads. And you will see the deployment called 'nginx' is available with two pods running.

list pods

Click the 'nginx' deployment to get detailed information about your deployment. You should see the 'nginx' deployment comes with two replicas and those two pods' replica is running.

list pods

Next, click on the Services menu to get the list of services available on your Kubernetes cluster. You should see the service called 'nginx' and 'Kubernetes' available on your cluster.

list services

Click the service 'nginx' to get detailed information about the service. Below is a similar page that will be shown on your Kubesphere dashboard.

detail service nginx

With this, you have now finished the deployment of Nginx pods to the Kubernetes cluster and verified the details of deployment from the kubesphere administration dashboard.

Conclusion

In this tutorial, you have now deployed the Kubernetes cluster and Kubesphre on multiple Ubuntu 22.04 servers. You have deployed Kubernetes with an automation tool called 'KubeKey' that developed by Kubesphere. You also have learned the basic configuration of Ubuntu servers for the Kubernetes deployment.

In addition to that, you have successfully installed and configured Kubesphere as the Kubernets web administration dashboard. You have larned the basic usage of Kubesphere for viwing Kubernetes cluster and the deployment, pods, and services.

To learn more about Kubesphere, visit the offical documentations of Kubesphere. As for Kubernetes, visit the Kubernets official documentation.

Share this page:

5 Comment(s)