website/content/zh/docs/v4.1/03-installation-and-upgrade/02-install-kubesphere/02-install-kubernetes-and-kubesphere.adoc

---
title: "安装 Kubernetes 和 KubeSphere"
linkTitle: "安装 Kubernetes 和 KubeSphere"
keywords: "Kubernetes, {ks_product}, 安装, 安装{ks_product_left}, 安装 Kubernetes"
description: "介绍如何在生产环境中安装 Kubernetes 和{ks_product_left}。"
weight: 02
---


本节介绍如何安装 Kubernetes 和{ks_product_left}。

安装过程中将用到开源工具 KubeKey。有关 KubeKey 的更多信息，请访问 link:https://github.com/kubesphere/kubekey[GitHub KubeKey 仓库]。


== 前提条件

* 您需要准备至少 1 台 Linux 服务器作为集群节点。在生产环境中，为确保集群具备高可用性，建议准备至少 5 台 Linux 服务器，其中 3 台作为控制平面节点，另外 2 台作为工作节点。如果您在多台 Linux 服务器上安装{ks_product_left}，请确保所有服务器属于同一子网。

* 集群节点的操作系统和版本须为 Ubuntu 16.04、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04、Debian 9、Debian 10、CentOS 7、CentOS Stream、RHEL 7、RHEL 8、SLES 15 或 openSUSE Leap 15。多台服务器的操作系统可以不同。关于其它操作系统和版本支持，请联系{ks_product_both}技术支持。

* 在生产环境中，为确保集群具有足够的计算和存储资源，建议每台集群节点配置至少 8 个 CPU 核心、16 GB 内存和 200 GB 磁盘空间。除此之外，建议在每台集群节点的 **/var/lib/docker**（对于 Docker）或 **/var/lib/containerd**（对于 containerd） 目录额外挂载至少 200 GB 磁盘空间用于存储容器运行时数据。

// :relfileprefix: ../../../

// include::../../../_custom/installationAndUpgrade/installationAndUpgrade-prer-offlineInstallation.adoc[]

// :relfileprefix: ./

* 在生产环境中，建议提前为{ks_product_both}集群配置高可用性以避免单个控制平面节点出现故障时集群服务中断。有关更多信息，请参阅link:../../../03-installation-and-upgrade/01-preparations/03-configure-high-availability/[配置高可用性]。
+
--
// Note
include::../../../../_ks_components/admonitions/note.adoc[]

如果您规划了多个控制平面节点，请务必提前为集群配置高可用性。

include::../../../../_ks_components/admonitions/admonEnd.adoc[]
--

* 默认情况下，{ks_product_right}使用集群节点的本地磁盘空间作为持久化存储。在生产环境中，建议提前配置外部存储系统作为持久化存储。有关更多信息，请参阅link:../../../03-installation-and-upgrade/01-preparations/04-configure-external-persistent-storage/[配置外部持久化存储]。

* 如果集群节点未安装容器运行时，安装工具 KubeKey 将在安装过程中自动为每个集群节点安装 Docker 作为容器运行时。您也可以提前手动安装 containerd、CRI-O 或 iSula 作为容器运行时。
+
--
// Note
include::../../../../_ks_components/admonitions/note.adoc[]

CRI-O 和 iSula 与{ks_product_both}的兼容性尚未经过充分测试，可能存在未知问题。

include::../../../../_ks_components/admonitions/admonEnd.adoc[]
--

* 请确保所有集群节点上 **/etc/resolv.conf** 文件中配置的 DNS 服务器地址可用。否则，{ks_product_right}集群可能会出现域名解析问题。

* 请确保在所有集群节点上都可以使用 **sudo**、**curl** 和 **openssl** 命令。

* 请确保所有集群节点时间同步。


== 配置防火墙规则

{ks_product_right}需要特定端口和协议用于服务之间的通信。如果您的基础设施环境已启用防火墙，您需要在防火墙设置中放行所需的端口和协议。如果您的基础设施环境未启用防火墙，您可以跳过此步骤。

下表列出需要在防火墙中放行的端口和协议。

[%header,cols="1a,1a,1a,1a,2a"]
|===
|服务 |协议 |起始端口 |结束端口 |备注

|ssh
|TCP
|22
|
|

|etcd
|TCP
|2379
|2380
|

|apiserver
|TCP
|6443
|
|

|calico
|TCP
|9099
|9100
|

|bgp
|TCP
|179
|
|

|nodeport
|TCP
|30000
|32767
|

|master
|TCP
|10250
|10258
|

|dns
|TCP
|53
|
|

|dns
|UDP
|53
|
|

|metrics-server
|TCP
|8443
|
|

|local-registry
|TCP
|5000
|
|离线环境需要

|local-apt
|TCP
|5080
|
|离线环境需要

|rpcbind
|TCP
|111
|
|使用 NFS 作为持久化存储时需要

|ipip
|IPENCAP/IPIP
|
|
|使用 Calico 时需要
|===

== 安装依赖项

您需要为所有集群节点安装 socat、conntrack、ebtables 和 ipset。如果上述依赖项在各集群节点上已存在，您可以跳过此步骤。

在 Ubuntu 操作系统上，执行以下命令为服务器安装依赖项：

// Bash
include::../../../../_ks_components/code/bash.adoc[]

sudo apt install socat conntrack ebtables ipset -y

----

如果集群节点使用其他操作系统，请将 **apt** 替换为操作系统对应的软件包管理工具。

== 创建 Kubernetes 集群

// ifeval::["{file_output_type}" == "pdf"]
// include::../../../_custom/installationAndUpgrade/installationAndUpgrade-oper-decompressInstallationPackage_new.adoc[]
// endif::[]

// ifeval::["{file_output_type}" == "html"]
include::../../../_custom/installationAndUpgrade/installationAndUpgrade-oper-downloadKubekey.adoc[]
// endif::[]


. 执行以下命令创建安装配置文件 **config-sample.yaml**：
+
--
// Bash
include::../../../../_ks_components/code/bash.adoc[]

 ./kk create config --with-kubernetes <Kubernetes version>
 
----

将 <Kubernetes version> 替换为实际需要的版本，例如 **v1.27.4**。{ks_product_right}默认支持 Kubernetes v1.21~1.28。

命令执行完毕后将生成安装配置文件 **config-sample.yaml**。

include::../../../_custom/installationAndUpgrade/installationAndUpgrade-note-doNotDeleteConfig_v4.adoc[]
--

. 执行以下命令编辑安装配置文件 **config-sample.yaml**：
+
--
// Bash
include::../../../../_ks_components/code/bash.adoc[]

vi config-sample.yaml
----

以下为部分示例配置文件，如需了解完整示例，请参阅link:https://github.com/kubesphere/kubekey/blob/master/docs/config-example.md[此文件]。

// YAML
include::../../../../_ks_components/code/yaml.adoc[]

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: sample
spec:
  hosts:
  - {name: controlplane1, address: 192.168.0.2, internalAddress: 192.168.0.2, port: 23, user: ubuntu, password: Testing123, arch: arm64} # arm64 节点注意添加参数 arch: arm64
  - {name: controlplane2, address: 192.168.0.3, internalAddress: 192.168.0.3, user: ubuntu, privateKeyPath: "~/.ssh/id_rsa"}
  - {name: worker1, address: 192.168.0.4, internalAddress: 192.168.0.4, user: ubuntu, password: Testing123}
  - {name: worker2, address: 192.168.0.5, internalAddress: 192.168.0.5, user: ubuntu, password: Testing123}
  - {name: registry, address: 192.168.0.6, internalAddress: 192.168.0.6, user: ubuntu, password: Testing123}
  roleGroups:
    etcd:
    - controlplane1
    - controlplane2
    control-plane:
    - controlplane1
    - controlplane2
    worker:
    - worker1
    - worker2
    # 如需使用 kk 自动部署镜像仓库，请设置 registry（建议镜像仓库与集群节点分离部署，减少相互影响）   
    registry:
    - registry
  controlPlaneEndpoint:
    internalLoadbalancer: haproxy # 如需部署⾼可⽤集群，且⽆负载均衡器可⽤，可开启该参数，做集群内部负载均衡
    domain: lb.kubesphere.local
    address: ""
    port: 6443
  kubernetes:
    version: v1.23.15
    clusterName: cluster.local
  network:
    plugin: calico
    kubePodsCIDR: 10.233.64.0/18
    kubeServiceCIDR: 10.233.0.0/18
    ## multus support. https://github.com/k8snetworkplumbingwg/multus-cni
    enableMultusCNI: false
  registry:
    # 如需使用 kk 部署 harbor，可将该参数设置为 harbor，不设置该参数且需使用 kk 部署容器镜像仓库，将默认部署 docker registry。
    # harbor 不支持 arm64，arm64 环境部署时，可不配置该参数。
    type: harbor
    # 如使用 kk 部署的 harbor 或其他需要登录的仓库，需设置对应仓库的 auths，如使用 kk 部署默认的 docker registry 仓库，则无需配置 auths 参数。
    # 注意：如使用 kk 部署 harbor，auths 参数请于创建 harbor 项目之后设置。
    auths:
      "dockerhub.kubekey.local": 
        username: admin # harbor 默认用户名
        password: Harbor12345 # harbor 默认密码
        plainHTTP: false  # 如果仓库使用 http，请将该参数设置为 true
    privateRegistry: "dockerhub.kubekey.local/kse"   # 设置集群部署时使用的私有仓库地址
    registryMirrors: []
    insecureRegistries: []
  addons: []

----
--

. 在 **config-sample.yaml** 配置文件的 **spec:hosts** 参数下设置各服务器的信息。
+
--
include::../../../_custom/installationAndUpgrade/installationAndUpgrade-para-hosts.adoc[]

--

. 在 **config-sample.yaml** 配置文件的 **spec:roleGroups** 参数下设置服务器的角色：
+
--
include::../../../_custom/installationAndUpgrade/installationAndUpgrade-para-roleGroups.adoc[]
--

. 如果您规划了多个控制平面节点，在 **config-sample.yaml** 配置文件的 **spec:controlPlaneEndpoint** 参数下设置高可用性信息。
+
--
include::../../../_custom/installationAndUpgrade/installationAndUpgrade-para-controlPlaneEndpoint.adoc[]
--

. 如果您需要使用外部持久化存储，在 **config-sample.yaml** 配置文件的 **spec:addons** 参数下设置外部持久化存储信息。
+
====
* 如果使用云上存储设备，在 **spec:addons** 下设置以下参数（将 <configuration file path> 替换为存储插件配置文件的实际路径）：
+
--
// Bash
[,bash]
----
  - name: csi-qingcloud
    namespace: kube-system
    sources:
      chart:
        name: csi-qingcloud
        repo: https://charts.kubesphere.io/test
        valuesFile: <configuration file path>
----
--

* 如果使用 NeonSAN 存储设备，在 **spec:addons** 下设置以下参数（将 <configuration file path> 替换为存储插件配置文件的实际路径）：
+
--
// Bash
[,bash]
----
  - name: csi-neonsan
    namespace: kube-system
    sources:
      chart:
        name: csi-neonsan
        repo: https://charts.kubesphere.io/test
        valuesFile: <configuration file path>
----
--

* 如果使用 NFS 存储系统，在 **spec:addons** 下设置以下参数（将 <configuration file path> 替换为存储插件配置文件的实际路径）：
+
--
// Bash
[,bash]
----
  - name: nfs-client
    namespace: kube-system
    sources:
      chart:
        name: nfs-client-provisioner
        repo: https://charts.kubesphere.io/main
        valuesFile: <configuration file path>
----
--
====

. 执行以下命令创建 Kubernetes 集群：
+
--
[,bash]
----
 ./kk create cluster -f config-sample.yaml
----

// Note
include::../../../../_ks_components/admonitions/note.adoc[]

如需使用 openebs localpv，可在命令后添加参数 --with-local-storage。如需对接其他存储，可在配置文件 addons 中添加配置相关存储插件，或 Kubernetes 集群部署完成后自行安装。

include::../../../../_ks_components/admonitions/admonEnd.adoc[]


如果显示如下信息，则表明 Kubernetes 集群创建成功。

[,yaml]
----
Pipeline[CreateclusterPipeline] execute successfully
----
--

== 安装{ks_product_left}

KubeSphere Core (ks-core) 是{ks_product_both}的核心组件，为扩展组件提供基础的运行环境。KubeSphere Core 安装完成后，即可访问{ks_product_left} Web 控制台。

. 在集群节点，执行以下命令安装 KubeSphere Core。
+
====
[,bash]
----
helm upgrade --install -n kubesphere-system --create-namespace ks-core https://charts.kubesphere.io/main/ks-core-1.1.0.tgz --debug --wait
----

如果显示如下信息，则表明 ks-core 安装成功：

[,yaml]
----
NOTES:
Thank you for choosing KubeSphere Helm Chart.

Please be patient and wait for several seconds for the KubeSphere deployment to complete.

1. Wait for Deployment Completion

    Confirm that all KubeSphere components are running by executing the following command:

    kubectl get pods -n kubesphere-system

2. Access the KubeSphere Console

    Once the deployment is complete, you can access the KubeSphere console using the following URL:

    http://192.168.6.10:30880

3. Login to KubeSphere Console

    Use the following credentials to log in:

    Account: admin
    Password: P@88w0rd

NOTE: It is highly recommended to change the default password immediately after the first login.

For additional information and details, please visit https://kubesphere.io.
----
====

. 从成功信息中的 **Console**、**Account** 和 **Password** 参数分别获取{ks_product_left} Web 控制台的 IP 地址、管理员用户名和管理员密码，并使用网页浏览器登录{ks_product_left} Web 控制台。
+
[.admon.note,cols="a"]
|===
|说明

|
取决于您的网络环境，您可能需要配置流量转发规则并在防火墙中放行 30880 端口。
|===

// 此时，{ks_product_right} Web 控制台仅提供{ks_product_both}的核心功能。

// * 若要使用扩展组件，还需link:../../../06-extension-user-guide/02-subscribe-and-install-components[订阅并安装扩展组件]。