addon使用指导 ​

背景信息 ​

openFuyao社区通过在BKECluster中放置addon数据，让调谐器在处理BKECluster时进行扩展件的安装。addon的介绍参见附录章节。

前提条件 ​

无。

使用限制 ​

无。

操作步骤 ​

按照下面步骤进行自定义addon的安装。

1. 编辑CR，添加所需的addon组件和所需参数。

   需要在BKEClusterCRD的Spec.ClusterConfig.Addons中声明自定义addon的参数，确保调谐器能识别并解析这些参数。

   参数格式：使用Param字段传递键值对。

   示例：自定义一个扩展件，需要指导镜像版本、副本数、自定义标签：

   yaml

   # BKECluster CR中配置自定义addon
   spec:
     clusterConfig:
       addons:
       - name: "my-addon"
         version: "v1.0.0"
         param:
           image: "my-registry/my-addon:v1.0.0"
           replicas: "3"
           labels: "app=my-addon, env=prod"
         block: true # 部署失败时是否阻塞整个流程

   参数解析：代码cluster-api-provider-bke/pkg/kube会通过prepareAddonParam函数将这些参数注入到YAML模板中，无需修改CRD结构，直接使用Param字段传递即可。

2. 准备addon的YAML模板。

   需要将addon的部署YAML（如Deployment、Service等）放在指定目录，确保调谐器能遍历并渲染这些模板。

   目录结构：在/etc/openFuyao/addons/manifests/kubernetes目录下，新建目录<addon-name>/<version>/，放入自定义的yaml文件，例如：

   text

   kubernetes/
     my-addon/
       v1.0.0/
         01-deployment.yaml
         02-service.yaml

   模板变量：YAML中需要替换的动态参数（如镜像地址、副本数）需使用模板占位符，调谐器会通过parseFabricParam等函数注入参数。

   说明：
   文件名前缀（如01-、02-）会影响部署顺序（升序执行），删除时会按降序执行。

   如下展示的是01-deployment.yaml文件，模板占位符会通过参数注入。

   yaml

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-addon
     namespace: {{.namespace}} # 由调谐器注入集群命名空间
   spec:
     replicas: {{.replicas}} # 引用addon参数中的replicas
     selector:
       matchLabels:
         app: my-addon
     template:
       metadata:
         labels: {{.labels}} # 引用addon参数中的labels
       spec:
         containers:
         - name: my-addon
           image: {{.image}} # 引用addon参数中的image

3. 处理addon的特殊逻辑（可选）。

   如果addon需要前置/后置操作（如创建Secret、配置权限、依赖其他组件），需在调谐器代码中添加自定义逻辑。

   • 前置操作：在EnsureAddonDeploy.addonBeforeCreateCustomOperate中添加分支，处理部署前的准备工作（如创建存储目录、配置RBAC）。
   • 后置操作：在EnsureAddonDeploy.addonAfterCreateCustomOperate中添加分支，处理部署后的收尾工作（如验证状态、注册资源）。

4. 执行部署。

   将自定义addon配置到BKEClusterCR的Spec.ClusterConfig.Addons中，调谐器会在EnsureAddonDeploy阶段检测到新addon，自动执行部署流程。 4.1. 对比Spec（期望状态）和Status.AddonStatus（实际状态），发现差异后触发部署。 4.2. 解析参数并渲染YAML模板。 4.3. 通过kube.InstallAddon调用kubectl apply部署到目标集群。 4.4. 更新Status.AddonStatus记录部署结果。

5. 验证部署。

   • 检查目标集群中是否创建了对应的资源（kubectl get deployment my-addon -n <namespace>）。
   • 查看BKECluster的状态（kubectl describe bkecluster <name> -n <namespace>），确认ClusterAddonCondition为True，且Status.AddonStatus包含my-addon的记录。

6. addon更新和卸载（可选）。

   • 更新：修改BKECluster中addon的version或param，调谐器会自动触发更新流程（重新渲染YAML并履约）。
   • 卸载：从Spec.ClusterConfig.Addons中移除addon，调谐器会按YAML文件名降序执行删除操作（kubectl delete -f <file>）。

附录 ​

下面介绍下常见扩展件的情况。

• K8s生态组件

  yaml

  - name: kubeproxy
    version: v1.33.1-of.1
    block: true # 可选，默认false。设置为true表示阻塞，即等待该组件启动完成后才会部署后续扩展件
    param: # 部署该组件需要的参数
      clusterNetworkMode: calico
  - name: calico
    version: v3.25.0
    param:
      calicoMode: bgp
  - name: coredns
    version: v1.10.1
  - name: nfs-csi
    version: v4.1.0
    block: true
    param:
      nfsServer: 172.28.8.186

  • 调谐器会按照配置顺序部署扩展件。
  • 如果有扩展件的安装强依赖前续扩展件拉起的服务，可以设置前续扩展件的block参数为true，执行阻塞式安装。
  • 如果需要安装非网络扩展件，将其放置在网络扩展件后面。

• 集群网络组件

  说明：
  1.请将网络组件根据下方示例结合实际情况选用不同组合，并将其写在addon最前方。
  2.为了保证后续的组件能正常启动，下面所示的有关集群网络的addon均需要添加设置block: true参数。
  3.详细的addon参数和参数说明解释，请看下方样例。

  下面介绍两种常见的网络插件，Fabric和Calico。

  说明：
  IPVS仅在使用Calico加kube-proxy时支持，Fabric不支持。

  • Fabric

    Fabric支持Overlay和Underlay两种模式。

    • Overlay模式

      Pod使用独立CIDR，通过VXLAN隧道封装跨节点通信，适用于底层网络受限场景。

      yaml

      addons:
      - name: fabric
        block: true
        param:
          fabricMode: overlay
          cidrBlock: "10.250.0.0/16" # 按实际情况填写，填写后同时设置bkecluster.spec.clusterConfig.cluster.networking.podSubnet与其一致
          excludeIps: "" # 没有则填写""，支持ip段和单个ip，使用英文","分割。eg:"10.250.0.1-10.250.0.10,10.250.0.55"
          tunnelType: vxlan # geneve gre erspan vxlan
          subCIDRMask: "24" # 按实际情况填写
        version: 2.6.2
      - name: coredns
        block: true
        version: v1.10.1

    • Underlay模式

      Pod直接使用VPC子网IP地址，依托于底层网络通信，无封装、高性能。

      yaml

      addons:
      - name: fabric
        block: true
        param:
          fabricMode: underlay
          cidrBlock: "10.250.0.0/16" # 按实际情况填写，填写后同时设置bkecluster.spec.clusterConfig.cluster.networking.podSubnet与其一致
          excludeIps: "" # 没有则填写""，支持ip段和单个ip，使用英文","分割。eg:"10.250.0.1-10.250.0.10,10.250.0.55"
          vlanID: "" # 按实际情况填写
          gateway: "10.250.0.254" # 按实际情况填写
          mask: "24" # 按实际情况填写
          dataPlaneUnified: "eth1" # 按实际情况填写
        version: 2.6.2
      - name: coredns
        block: true
        version: v1.10.1

  • Calico

    根据实际业务需求，可通过以下参数调整配置：

    • calicoMode：用于设置Calico的网络模式，可选值为vxlan、bgp、ipip。
    • proxyMode：用于设置kube-proxy的转发模式，可选值为iptables、ipvs，该参数为可选。
    yaml

    # kube-proxy版本以k8s版本为准
    - name: kubeproxy
      param:
        proxyMode: iptables # iptables、ipvs
      version: v1.33.1-of.1
      block: true
    - name: calico
      param:
        calicoMode: vxlan # vxlan bgp ipip
      version: v3.25.0
      block: true
    - name: coredns
      version: v1.10.1
      block: true