Deploy K3s and KubeSphere

K3s is a lightweight Kubernetes distribution built for IoT and edge computing with external dependencies minimized. It is packaged as a single binary that reduces the dependencies and steps that are required to set up a Kubernetes cluster.

You can use KubeKey to install both K3s and KubeSphere while KubeSphere can also be deployed on an existing K3s cluster.

Note

Currently, KubeSphere on K3s is only for testing and development as some features have not been fully tested.

Prerequisites

  • For information about the prerequisites for K3s installation, see the K3s documentation.
  • You may need to create necessary firewall rules or port forwarding rules depending on your environment. For more information, see Port Requirements.

Step 1: Download KubeKey

Follow the step below to download KubeKey.

Download KubeKey from its GitHub Release Page or use the following command directly.

  1. curl -sfL https://get-kk.kubesphere.io | VERSION=v2.2.1 sh -

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

  1. export KKZONE=cn

Run the following command to download KubeKey:

  1. curl -sfL https://get-kk.kubesphere.io | VERSION=v2.2.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 steps below.

Note

The commands above download the latest release (v2.2.1) of KubeKey. Note that an earlier version of KubeKey cannot be used to install K3s.

Make kk executable:

  1. chmod +x kk

Step 2: Create a Cluster

  1. Create a configuration file of your cluster by running the following command:

    1. ./kk create config --with-kubernetes v1.21.4-k3s --with-kubesphere v3.3.0

    Note

    KubeKey v2.2.1 supports the installation of K3s v1.21.4.

  2. A default file config-sample.yaml will be created if you do not customize the name. Edit the file.

    1. vi config-sample.yaml
    1. ...
    2. metadata:
    3.   name: sample
    4. spec:
    5.   hosts:
    6.   - {name: master, address: 192.168.0.2, internalAddress: 192.168.0.2, user: ubuntu, password: Testing123}
    7.   - {name: node1, address: 192.168.0.3, internalAddress: 192.168.0.3, user: ubuntu, password: Testing123}
    8.   - {name: node2, address: 192.168.0.4, internalAddress: 192.168.0.4, user: ubuntu, password: Testing123}
    9.   roleGroups:
    10.     etcd:
    11.     - master
    12.     control-plane:
    13.     - master
    14.     worker:
    15.     - node1
    16.     - node2
    17.   controlPlaneEndpoint:
    18.     domain: lb.kubesphere.local
    19.     address: ""
    20.     port: 6443
    21.   kubernetes:
    22.     version: v1.21.4-k3s
    23.     imageRepo: kubesphere
    24.     clusterName: cluster.local
    25.   network:
    26.     plugin: calico
    27.     kubePodsCIDR: 10.233.64.0/18
    28.     kubeServiceCIDR: 10.233.0.0/18
    29.   registry:
    30.     registryMirrors: []
    31.     insecureRegistries: []
    32.   addons: []
    33. ...

    Note

    For more information about each field in the configuration file, see an example file.

  3. Save the file and execute the following command to install K3s and KubeSphere:

    1. ./kk create cluster -f config-sample.yaml

  4. When the installation finishes, you can inspect installation logs with the following command:

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

    Expected output:

    1. #####################################################
    2. ###              Welcome to KubeSphere!           ###
    3. #####################################################
    5. Console: http://192.168.0.2:30880
    6. Account: admin
    7. Password: [email protected]
    9. NOTES：
    10.   1. After you log into the console, please check the
    11.      monitoring status of service components in
    12.      "Cluster Management". If any service is not
    13.      ready, please wait patiently until all components
    14.      are up and running.
    15.   2. Please change the default password after login.
    17. #####################################################
    18. https://kubesphere.io             20xx-xx-xx xx:xx:xx
    19. #####################################################

  5. Access the KubeSphere console at <NodeIP>:30880 with the default account and password (admin/[[email protected]](https://kubesphere.io/cdn-cgi/l/email-protection)).

Note

You can enable pluggable components of KubeSphere after the installation while some features may not be compatible as KubeSphere on K3s is only experimental currently.