How To Install KubeSphere on Ubuntu 24.04 LTS

KubeSphere is an open-source container management platform that simplifies the deployment and management of containerized applications. Built on Kubernetes, it provides a user-friendly interface and a rich set of features for developers and DevOps teams. This guide will walk you through the step-by-step process of installing KubeSphere on Ubuntu 24.04 LTS, ensuring you have a robust environment for your container orchestration needs.

Prerequisites

System Requirements

Before diving into the installation process, ensure that your system meets the following minimum hardware requirements:

• CPU: 2 cores or more
• RAM: At least 4 GB (8 GB recommended)
• Disk Space: Minimum of 20 GB free space

Software Requirements

You will need to have Ubuntu 24.04 LTS installed on your machine. Additionally, ensure that you have the following software packages:

• Docker: The container runtime required for KubeSphere.
• KubeKey: A tool for deploying Kubernetes clusters.

User Permissions

You must have sudo access to install software packages and configure system settings. If you are not logged in as a root user, ensure that your user account has administrative privileges.

Preparing the Environment

Update and Upgrade the System

The first step in preparing your Ubuntu system is to update the package index and upgrade all installed packages. Open your terminal and execute the following commands:

sudo apt update && sudo apt upgrade -y

This ensures that you are working with the latest versions of packages available in the repository.

Install Docker

KubeSphere requires Docker to manage containers effectively. To install Docker, run the following command:

sudo apt install -y docker.io

Once installed, enable Docker to start on boot with this command:

sudo systemctl enable docker

You can verify the Docker installation by checking its version:

docker --version

Install Required Packages

You may also need to install additional packages for managing Kubernetes clusters. Install these using:

sudo apt install -y curl wget jq vim net-tools

Installing KubeKey

Download KubeKey

KubeKey is a lightweight tool designed to simplify Kubernetes installation. To download KubeKey, use the following command:

curl -sfL https://get-kk.kubesphere.io | sh -

This command fetches and executes the installation script from KubeSphere’s official source.

Set Executable Permissions

After downloading, you need to set executable permissions for KubeKey:

chmod +x kk

Configure Download Region (if necessary)

If you are located in China or prefer a different download region, set the KKZONE environment variable accordingly:

export KKZONE=cn

Creating the Installation Configuration

Generate Configuration File

Create a configuration file for your KubeSphere installation by running the following command:

./kk create config --with-kubernetes 

This command generates a YAML configuration file based on your specified Kubernetes version.

Edit Configuration File

Edit the generated configuration file using your preferred text editor (e.g., vim or nano) to customize settings such as networking options or storage classes as needed:

nano config.yaml

This file will guide KubeKey during the installation process.

Installing KubeSphere

Run the Installation Command

You are now ready to initiate the installation of KubeSphere along with Kubernetes. Execute the following command, replacing `<kubernetes-version>` and `<kubesphere-version>` with your desired versions:

./kk create cluster --with-kubernetes v1.22.12 --with-kubesphere v3.4.1

This command will begin downloading necessary images and configuring your cluster based on your YAML settings.

Monitoring Installation Progress

You can monitor the installation progress by checking the status of pods and services with these commands:

kubectl get pods -n kubesphere-system
kubectl get svc -n kubesphere-system

This will help you ensure that all components are being deployed correctly.

Accessing KubeSphere Dashboard

Once installation is complete, access the KubeSphere dashboard through your web browser. The default URL is typically http://your-IP-address:30880/. Log in using default credentials:

• User: admin
• Password: P@88w0rd

You can change these credentials after logging in for security purposes.

Post-Installation Steps

Verifying Installation

The final step is to verify that KubeSphere is running correctly. Use this command to check if all pods are up and running:

kubectl get pods -n kubesphere-system

If all pods show a status of “Running,” congratulations! Your KubeSphere installation was successful.

Default Credentials for Login

The default login credentials provided above should be changed immediately after your first login to enhance security. Navigate to Account Settings in the dashboard to update your password.

Troubleshooting Common Issues

If you encounter issues during installation or operation, consider these common troubleshooting tips:

• PODS Not Starting: If any pods are stuck in “Pending” status, check if your system meets resource requirements or if there are any network issues.
• Docker Daemon Not Running: If Docker fails to start, ensure it is enabled and running using:

  sudo systemctl start docker
  sudo systemctl enable docker

• Kubernetes API Unreachable: If you cannot access Kubernetes API, verify that kube-apiserver is running:

  kubectl get pods -n kube-system | grep apiserver

• KubeSphere Dashboard Not Accessible: If you cannot access the dashboard, check firewall settings or ensure that port 30880 is open.
• Error Messages During Installation: If you encounter specific error messages during installation, refer to official documentation or community forums for solutions.
• No Resources Available Error: If this error occurs during pod creation, consider increasing available resources or adjusting configurations in your YAML file.
• Persistent Volume Issues: If persistent volumes do not bind correctly, check storage class configurations and ensure proper permissions are set on storage backends.
• POD Crash Looping:
  If pods crash repeatedly, check logs with:

  kubectl logs 

  This will provide insights into what might be causing failures.

Congratulations! You have successfully installed KubeSphere. Thanks for using this tutorial for installing the KubeSphere open-source container platform on Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official KubeSphere website.