Last updated:

All-in-One Installation of Kubernetes and KubeSphere on Linux

For those who are new to KubeSphere and looking for a quick way to discover the container platform, the all-in-one mode is your best choice to get started. It features rapid deployment and hassle-free configurations with KubeSphere and Kubernetes all provisioned on your machine.

Video Demonstration

Step 1: Prepare a Linux Machine

To get started with all-in-one installation, you only need to prepare one host according to the following requirements for hardware and operating system.

Hardware Recommendations

OS	Minimum Requirements
Ubuntu 16.04, 18.04	2 CPU cores, 4 GB memory, and 40 GB disk space
Debian Buster, Stretch	2 CPU cores, 4 GB memory, and 40 GB disk space
CentOS 7.x	2 CPU cores, 4 GB memory, and 40 GB disk space
Red Hat Enterprise Linux 7	2 CPU cores, 4 GB memory, and 40 GB disk space
SUSE Linux Enterprise Server 15/openSUSE Leap 15.2	2 CPU cores, 4 GB memory, and 40 GB disk space

Note

The preceding system requirements and the following instructions are for the default minimal installation without any pluggable components enabled. If your machine has at least 8 CPU cores and 16 GB memory, it is recommended that you enable all components. For more information, see Enable Pluggable Components.

Node requirements

The node can be accessed through SSH.
sudo/curl/openssl should be used.

Container runtimes

Your cluster must have an available container runtime. If you use KubeKey to set up a cluster, KubeKey installs the latest version of Docker by default. Alternatively, you can manually install Docker or other container runtimes before you create a cluster.

Supported Container Runtime	Version
Docker	19.3.8 +
containerd (experimental, not fully tested)	Latest
CRI-O (experimental, not fully tested)	Latest
iSula (experimental, not fully tested)	Latest

Note

To deploy KubeSphere in an offline environment, you must install a container runtime in advance.

Dependency requirements

KubeKey can install Kubernetes and KubeSphere together. The dependency that needs to be installed may be different based on the Kubernetes version to be installed. You can refer to the following list to see if you need to install relevant dependencies on your node in advance.

Dependency	Kubernetes Version ≥ 1.18	Kubernetes Version < 1.18
`socat`	Required	Optional but recommended
`conntrack`	Required	Optional but recommended
`ebtables`	Optional but recommended	Optional but recommended
`ipset`	Optional but recommended	Optional but recommended

Info

Developed in Go, KubeKey represents a brand-new installation tool as a replacement for the ansible-based installer used before. KubeKey provides users with flexible installation choices, as they can install KubeSphere and Kubernetes separately or install them at one time, which is convenient and efficient.

Network and DNS requirements

Make sure the DNS address in /etc/resolv.conf is available. Otherwise, it may cause some issues of DNS in the cluster.
If your network configuration uses firewall rules or security groups, you must ensure infrastructure components can communicate with each other through specific ports. It is recommended that you turn off the firewall. For more information, see Port Requirements.
Supported CNI plugins: Calico and Flannel. Others (such as Cilium and Kube-OVN) may also work but note that they have not been fully tested.

Tip

It is recommended that your OS be clean (without any other software installed). Otherwise, there may be conflicts.
It is recommended that a registry mirror (a booster) be prepared if you have trouble downloading images from dockerhub.io. For more information, see Configure a Booster for Installation.

Step 2: Download KubeKey

Perform the following steps to download KubeKey.

Download KubeKey from its GitHub Release Page or run the following command:

curl -sfL https://get-kk.kubesphere.io | VERSION=v1.1.1 sh -

Run the following command first to make sure you download KubeKey from the correct zone.

export KKZONE=cn

Run the following command to download KubeKey:

curl -sfL https://get-kk.kubesphere.io | VERSION=v1.1.1 sh -

Note

After you download KubeKey, if you transfer it to a new machine also with poor network connections to Googleapis, you must run export KKZONE=cn again before you proceed with the following steps.

Note

The commands above download the latest release (v1.1.1) of KubeKey. You can change the version number in the command to download a specific version.

Make kk executable:

chmod +x kk

Step 3: Get Started with Installation

You only need to run one command for all-in-one installation. The template is as follows:

./kk create cluster [--with-kubernetes version] [--with-kubesphere version]

To create a Kubernetes cluster with KubeSphere installed, refer to the following command as an example:

./kk create cluster --with-kubernetes v1.20.4 --with-kubesphere v3.1.1

Note

Recommended Kubernetes versions for KubeSphere v3.1.1: v1.17.9, v1.18.8, v1.19.8 and v1.20.4. If you do not specify a Kubernetes version, KubeKey installs Kubernetes v1.19.8 by default. For more information about supported Kubernetes versions, see Support Matrix.
For all-in-one installation, you do not need to change any configuration.
If you do not add the flag --with-kubesphere in the command in this step, KubeSphere will not be deployed. KubeKey will install Kubernetes only. If you add the flag --with-kubesphere without specifying a KubeSphere version, the latest version of KubeSphere will be installed.
KubeKey will install OpenEBS to provision LocalPV for the development and testing environment by default, which is convenient for new users. For other storage classes, see Persistent Storage Configurations.

After you run the command, you will see a table for environment check. For details, see Node requirements and Dependency requirements. Type yes to continue.

Step 4: Verify the Installation

If the following information is displayed, Kubernetes and KubeSphere is successfully installed.

Installation-complete

Run the following command to check the result.

kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system -l app=ks-install -o jsonpath='{.items[0].metadata.name}') -f

The output displays the IP address and port number of the web console, which is exposed through NodePort 30880 by default. Now, you can access the console at <NodeIP>:30880 with the default account and password (admin/P@88w0rd).

#####################################################
###              Welcome to KubeSphere!           ###
#####################################################

Console: http://192.168.0.2:30880
Account: admin
Password: P@88w0rd

NOTES：
  1. After you log into the console, please check the
     monitoring status of service components in
     "Cluster Management". If any service is not
     ready, please wait patiently until all components 
     are up and running.
  2. Please change the default password after login.

#####################################################
https://kubesphere.io             20xx-xx-xx xx:xx:xx
#####################################################

Note

You may need to configure port forwarding rules and open the port in your security group so that external users can access the console.

After logging in to the console, you can check the status of different components in Components. You may need to wait for some components to be up and running if you want to use related services. You can also use kubectl get pod --all-namespaces to inspect the running status of KubeSphere workloads.

kubesphere-components

Enable Pluggable Components (Optional)

This guide is used only for the minimal installation by default. For more information about how to enable other components in KubeSphere, see Enable Pluggable Components.

Code Demonstration

Feedback

Was this page Helpful?

Thanks for the feedback. If you have a specific question about how to use KubeSphere, ask it on Slack. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.

What’s on this Page