English | δΈζ
π Welcome to KubeKey!
KubeKey is an open-source lightweight tool for deploying Kubernetes clusters. It provides a flexible, rapid, and convenient way to install Kubernetes/K3s only, both Kubernetes/K3s and KubeSphere, and related cloud-native add-ons. It is also an efficient tool to scale and upgrade your cluster.
In addition, KubeKey also supports customized Air-Gap package, which is convenient for users to quickly deploy clusters in offline environments.
KubeKey has passed CNCF kubernetes conformance verification.
Use KubeKey in the following three scenarios.
- Install Kubernetes/K3s only
- Install Kubernetes/K3s and KubeSphere together in one command
- Install Kubernetes/K3s first, then deploy KubeSphere on it using ks-installer
Important: If you have existing Kubernetes clusters, please refer to ks-installer (Install KubeSphere on existing Kubernetes cluster).
Supported Environment
Linux Distributions
- Ubuntu 16.04, 18.04, 20.04
- Debian Buster, Stretch
- CentOS/RHEL 7
- SUSE Linux Enterprise Server 15
Recommended Linux Kernel Version:
4.15 or later
You can run theuname -srm
command to check the Linux Kernel Version.
Kubernetes Versions
- v1.17: β v1.17.9
- v1.18: β v1.18.6
- v1.19: β v1.19.8
- v1.20: β v1.20.6
- v1.21: β v1.21.5 (default)
- v1.22: β v1.22.1
Looking for more supported versions Click here
Container Manager
- Docker / containerd / CRI-O / iSula
Kata Containers
can be set to automatically install and configure runtime class for it when the container manager is containerd or CRI-O.
Network Plugins
- Calico / Flannel / Cilium / Kube-OVN / Multus-CNI
Kubekey also supports users to set the network plugin to
none
if there is a requirement for custom network plugin.
Requirements and Recommendations
- Minimum resource requirements (For Minimal Installation of KubeSphere only)οΌ
- 2 vCPUs
- 4 GB RAM
- 20 GB Storage
/var/lib/docker is mainly used to store the container data, and will gradually increase in size during use and operation. In the case of a production environment, it is recommended that /var/lib/docker mounts a drive separately.
- OS requirements:
SSH
can access to all nodes.- Time synchronization for all nodes.
sudo
/curl
/openssl
should be used in all nodes.docker
can be installed by yourself or by KubeKey.Red Hat
includesSELinux
in itsLinux release
. It is recommended to close SELinux or switch the mode of SELinux toPermissive
- It's recommended that Your OS is clean (without any other software installed), otherwise there may be conflicts.
- A container image mirror (accelerator) is recommended to be prepared if you have trouble downloading images from dockerhub.io. Configure registry-mirrors for the Docker daemon.
- KubeKey will install OpenEBS to provision LocalPV for development and testing environment by default, this is convenient for new users. For production, please use NFS / Ceph / GlusterFS or commercial products as persistent storage, and install the relevant client in all nodes.
- If you encounter
Permission denied
when copying, it is recommended to check SELinux and turn off it first
- 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 list below to see if you need to install relevant dependencies on your node in advance.
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 |
ipvsadm |
Optional but recommended | Optional but recommended |
- Networking and DNS requirements:
- Make sure the DNS address in
/etc/resolv.conf
is available. Otherwise, it may cause some issues of DNS in cluster. - If your network configuration uses Firewall or Security GroupοΌyou must ensure infrastructure components can communicate with each other through specific ports. It's recommended that you turn off the firewall or follow the link configuriation: NetworkAccess.
- Make sure the DNS address in
Usage
Get the KubeKey Executable File
-
The fastest way to get KubeKey is to use the script:
curl -sfL https://get-kk.kubesphere.io | sh -
-
Binary downloads of the KubeKey also can be found on the Releases page. Unpack the binary and you are good to go!
-
Build Binary from Source Code
git clone https://github.com/kubesphere/kubekey.git cd kubekey ./build.sh
Note:
- Docker needs to be installed before building.
- If you have problem to access
https://proxy.golang.org/
, excutebuild.sh -p
instead.
Create a Cluster
Quick Start
Quick Start is for all-in-one
installation which is a good start to get familiar with Kubernetes and KubeSphere.
Note: Since Kubernetes temporarily does not support uppercase NodeName, contains uppercase letters in the hostname will lead to subsequent installation error
Command
If you have problem to access
https://storage.googleapis.com
, execute firstexport KKZONE=cn
.
./kk create cluster [--with-kubernetes version] [--with-kubesphere version]
Examples
-
Create a pure Kubernetes cluster with default version.
./kk create cluster
-
Create a Kubernetes cluster with a specified version (supported versions).
./kk create cluster --with-kubernetes v1.19.8
-
Create a Kubernetes cluster with KubeSphere installed (e.g.
--with-kubesphere v3.1.0
)./kk create cluster --with-kubesphere [version]
Advanced
You have more control to customize parameters or create a multi-node cluster using the advanced installation. Specifically, create a cluster by specifying a configuration file.
If you have problem to access
https://storage.googleapis.com
, execute firstexport KKZONE=cn
.
-
First, create an example configuration file
./kk create config [--with-kubernetes version] [--with-kubesphere version] [(-f | --filename) path]
examples:
- create an example config file with default configurations. You also can specify the file that could be a different filename, or in different folder.
./kk create config [-f ~/myfolder/abc.yaml]
- with KubeSphere
./kk create config --with-kubesphere
-
Modify the file config-sample.yaml according to your environment
Note: Since Kubernetes temporarily does not support uppercase NodeName, contains uppercase letters in workerNode`s name will lead to subsequent installation error
A persistent storage is required in the cluster, when kubesphere will be installed. The local volume is used default. If you want to use other persistent storage, please refer to addons.
-
Create a cluster using the configuration file
./kk create cluster -f config-sample.yaml
Enable Multi-cluster Management
By default, KubeKey will only install a solo cluster without Kubernetes federation. If you want to set up a multi-cluster control plane to centrally manage multiple clusters using KubeSphere, you need to set the ClusterRole
in config-example.yaml. For multi-cluster user guide, please refer to How to Enable the Multi-cluster Feature.
Enable Pluggable Components
KubeSphere has decoupled some core feature components since v2.1.0. These components are designed to be pluggable which means you can enable them either before or after installation. By default, KubeSphere will be started with a minimal installation if you do not enable them.
You can enable any of them according to your demands. It is highly recommended that you install these pluggable components to discover the full-stack features and capabilities provided by KubeSphere. Please ensure your machines have sufficient CPU and memory before enabling them. See Enable Pluggable Components for the details.
Add Nodes
Add new node's information to the cluster config file, then apply the changes.
./kk add nodes -f config-sample.yaml
Delete Nodes
You can delete the node by the following commandοΌthe nodeName that needs to be removed.
./kk delete node <nodeName> -f config-sample.yaml
Delete Cluster
You can delete the cluster by the following command:
- If you started with the quick start (all-in-one):
./kk delete cluster
- If you started with the advanced (created with a configuration file):
./kk delete cluster [-f config-sample.yaml]
Upgrade Cluster
Allinone
Upgrading cluster with a specified version.
./kk upgrade [--with-kubernetes version] [--with-kubesphere version]
- Support upgrading Kubernetes only.
- Support upgrading KubeSphere only.
- Support upgrading Kubernetes and KubeSphere.
Multi-nodes
Upgrading cluster with a specified configuration file.
./kk upgrade [--with-kubernetes version] [--with-kubesphere version] [(-f | --filename) path]
- If
--with-kubernetes
or--with-kubesphere
is specified, the configuration file will be also updated. - Use
-f
to specify the configuration file which was generated for cluster creation.
Note: Upgrading multi-nodes cluster need a specified configuration file. If the cluster was installed without kubekey or the configuration file for installation was not found, the configuration file needs to be created by yourself or following command.
Getting cluster info and generating kubekey's configuration file (optional).
./kk create config [--from-cluster] [(-f | --filename) path] [--kubeconfig path]
--from-cluster
means fetching cluster's information from an existing cluster.-f
refers to the path where the configuration file is generated.--kubeconfig
refers to the path where the kubeconfig.- After generating the configuration file, some parameters need to be filled in, such as the ssh information of the nodes.
Documents
- Features List
- Commands
- Configuration example
- Air-Gapped Installation
- Highly Available clusters
- Addons
- Network access
- Storage clients
- kubectl auto-completion
- kubekey auto-completion
- Roadmap
- Check-Renew-Certificate
- Developer-Guide
Contributors β¨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!