二进制文件自定义使用指导

背景信息

本文档介绍如何使用Custom Resource(CR)来动态配置Kubelet和Containerd组件。在bc中有对kubelet和containerd的配置cr的引用。kubelet的cr缩写为kct，containerd的cr缩写为cct。可以编辑kct和cct完成对自定义的kubelet和containerd配置项导入。

前提条件

创建集群中使用CR来完成Kubelet和Containerd配置。

使用限制

无。

使用教程

KubeletConfig CR配置

概述

KubeletConfigCR允许通过Kubernetes资源来动态配置Kubelet的配置文件和systemd服务文件，而无需手动编辑节点上的文件。

CR结构

apiVersion: bke.bocloud.com/v1beta1
kind: KubeletConfig
metadata:
  name: <config-name>
  namespace: <namespace>  # 默认为 bke-system
spec:
  kubeletConfig:
    kubelet.conf:
      raw: |
        # Kubelet 配置文件的 YAML 内容
  kubeletService:
    service:
      # Kubelet systemd 服务配置

spec字段说明

spec.kubeletConfig

用于配置Kubelet的配置文件(/var/lib/kubelet/config.yaml)。

参数	类型	是否必选	描述
`kubelet.conf`	`map[string]RawExtension`	是	包含`raw`字段的配置对象
`kubelet.conf.raw`	`string`	是	Kubelet配置文件的完整YAML内容

raw 字段格式：

raw字段应包含完整的Kubelet配置文件YAML内容，例如：

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd
clusterDNS:
  - 10.96.0.10
clusterDomain: cluster.local
...

kubelet.config实现对填写的kubelet.conf.raw的透传，需要由用户保证传入的配置项正确。

spec.kubeletService

用于配置Kubelet的systemd服务文件(/etc/systemd/system/kubelet.service)。

参数	类型	是否必选	描述
`service`	`KubeletService`	否	Kubelet systemd服务配置对象

kubeletService 字段说明：

参数	类型	是否必选	描述
`ExecStart`	`string`	否	服务启动命令
`Restart`	`string`	否	重启策略(如：always，on-failure)
`RestartSec`	`string`	否	重启间隔时间(如：5s，10s)
`StartLimitInterval`	`string`	否	启动限制时间窗口
`StartLimitBurst`	`int`	否	启动限制次数
`KillMode`	`string`	否	终止模式(如：control-group，process)
`StandardOutput`	`string`	否	标准输出重定向 (如：journal，null)
`StandardError`	`string`	否	标准错误重定向
`SyslogIdentifier`	`string`	否	系统日志标识符
`WorkingDirectory`	`string`	否	工作目录
`User`	`string`	否	运行用户
`Group`	`string`	否	运行组
`ExecStartPre`	`[]string`	否	启动前执行的命令列表
`Environment`	`[]string`	否	环境变量列表 (格式：KEY=VALUE)
`EnvironmentFile`	`[]string`	否	环境变量文件路径列表
`CustomExtra`	`map[string]string`	否	自定义额外配置项(键值对)

kubelet.service是对kubelet启动时service支持的配置项。

kubelet动态传值功能

动态传值机制允许在配置文件中使用变量，这些变量会在部署时被实际值替换。这提供了极大的灵活性，使得同一份配置可以适用于不同的节点和环境。

启用变量替换

在BKECluster的部署过程中，系统会自动检测KubeletConfigRef，并启用变量替换功能。变量替换会在以下两个地方生效：

kubelet.conf配置
kubelet.servicesystemd服务文件

表达式变量：${EXPR|command|END}

执行shell命令并将输出作为变量值。

语法：

${EXPR|shell_command|END}

示例：

spec:  kubeletConfig:    
  kubelet.conf:      
    raw: |        
        apiVersion: kubelet.config.k8s.io/v1beta1
        kind: KubeletConfiguration
        # 获取 CPU 核心数
        cpuManagerPolicy: "static"
        reservedSystemCPUs: "${EXPR|nproc|END}"
        # 获取内存大小（MB）
        evictionHard:
          memory.available: "${EXPR|free -m | grep Mem | awk '{print $2}'|END}Mi"
        # 获取主机名
        hostnameOverride: "${EXPR|hostname|END}"

说明：

命令会在目标节点上执行。

命令执行失败时，变量会保持原样（不替换）。

命令输出会去除首尾空白字符。

kubelet配置文件kct参考

my-kubelet.yaml

apiVersion: bke.bocloud.com/v1beta1
kind: KubeletConfig
metadata:
  name: my-kubelet
  namespace: my-kubelet
  labels:
    test: "true"
    component: "kubelet"
spec:

  kubeletConfig:
    kubelet.conf:
      raw: |
        apiVersion: kubelet.config.k8s.io/v1beta1
        kind: KubeletConfiguration
        authentication:
          anonymous:
            enabled: false
          webhook:
            cacheTTL: 2m0s
            enabled: true
          x509:
            clientCAFile: /etc/kubernetes/pki/ca.crt
        authorization:
          mode: Webhook
          webhook:
            cacheAuthorizedTTL: 5m0s
            cacheUnauthorizedTTL: 30s
        address: "${EXPR|ip -4 addr show | awk '/inet / {split($2,a,"/"); print a[1]}' | grep -vE '^127\.0\.0\.1|^169\.254\.' | head -n1|END}"
        port: 10250
        readOnlyPort: 0
        cgroupDriver: systemd
        hairpinMode: promiscuous-bridge
        serializeImagePulls: false
        clusterDNS:
          - "10.96.0.10"
        clusterDomain: "cluster.local"
        healthzBindAddress: 127.0.0.1
        healthzPort: 10248
        rotateCertificates: true
        staticPodPath: /etc/kubernetes/manifests
        streamingConnectionIdleTimeout: 4h0m0s
        syncFrequency: 1m0s
        volumeStatsAggPeriod: 1m0s

  kubeletService:
    enabled: true
    serviceName: "kubelet"
    unit:
      description: "Kubernetes Kubelet (my-Test)"
      documentation: "https://kubernetes.io/docs/concepts/overview/components/#kubelet"
      after:
        - "containerd.service"
        - "network-online.target"
      wants:
        - "network-online.target"
      requires:
        - "containerd.service"
    service:
      workingDirectory: "/var/lib/kubelet"
      execStartPre:
        - "/usr/bin/mkdir -p /sys/fs/cgroup/cpuacct/system.slice/kubelet.service"
        - "/usr/bin/mkdir -p /sys/fs/cgroup/hugetlb/system.slice/kubelet.service"
      execStart: "/usr/bin/kubelet \
      --bootstrap-kubeconfig=/etc/kubernetes/bootstrap-kubelet.conf \
      --kubeconfig=/etc/kubernetes/admin.conf \
      --config=/var/lib/kubelet/config.yaml \
      --container-runtime-endpoint=unix:///run/containerd/containerd.sock \
      --pod-infra-container-image=registry.k8s.io/pause:3.9 \
      --cgroup-driver=systemd \
      --register-node=true \
      --v=2 \
      --node-ip=${EXPR|ip -4 addr show scope global | awk '/inet /{print $2}' | cut -d'/' -f1|END} \
      --hostname-override=${EXPR|hostname -i | awk '{print $1}'|END}
      "
      restart: "always"
      restartSec: 10
      startLimitInterval: 30
      startLimitBurst: 3
      killMode: "process"
      standardOutput: "syslog"
      standardError: "syslog"
      syslogIdentifier: "kubelet"
      user: "root"
      group: "root"

    install:
      wantedBy:
        - "multi-user.target"
      requiredBy: []

    variables:
      kubeletBinaryPath: "/usr/bin/kubelet"
      kubeletConfigPath: "/etc/kubernetes/kubelet.conf"
      nodeName: "test-node-01"
      nodeIP: "xx"
      containerdEndpoint: "unix:///run/containerd/containerd.sock"
      pauseImage: "registry.aliyuncs.com/google_containers/pause:3.9"

ContainerdConfig CR配置

概述

ContainerdConfigCR允许通过Kubernetes资源来动态配置Containerd的主配置文件、服务文件和镜像仓库配置。

CR结构

apiVersion: bke.bocloud.com/v1beta1
kind: ContainerdConfig
metadata:
  name: <config-name>
  namespace: <namespace>
spec:
  script:
    # 脚本配置
  service:
    # Containerd systemd 服务配置
  main:
    # Containerd 主配置文件 (config.toml)
  registry:
    # 镜像仓库配置

spec字段说明

spec.script

用于在配置Containerd前执行自定义脚本。

参数	类型	是否必选	描述
`Content`	`string`	否	脚本内容(内联脚本)
`Path`	`string`	否	脚本文件路径(本地文件)
`Interpreter`	`string`	否	解释器(如：/bin/bash, /bin/sh)，默认为/bin/bash
`Args`	`[]string`	否	传递给脚本的参数列表

说明：
Content和Path二选一，如果都提供则优先使用Content。

spec.service

用于配置Containerd的systemd服务drop-in文件(/etc/systemd/system/containerd.service.d/10-override.conf)。

参数	类型	是否必选	描述
`ExecStart`	`string`	否	服务启动命令
`Slice`	`string`	否	systemd slice单元
`KillMode`	`string`	否	终止模式
`Restart`	`string`	否	重启策略
`RestartSec`	`string`	否	重启间隔时间
`TimeoutStopSec`	`string`	否	停止超时时间
`StartLimitInterval`	`string`	否	启动限制时间窗口
`StartLimitBurst`	`int`	否	启动限制次数
`Logging`	`LoggingConfig`	否	日志配置
`CustomExtra`	`map[string]string`	否	自定义额外配置项

LoggingConfig字段：

参数	类型	是否必选	描述
`StandardOutput`	`string`	否	标准输出重定向
`StandardError`	`string`	否	标准错误重定向
`SyslogIdentifier`	`string`	否	系统日志标识符
`LogLevelMax`	`string`	否	最大日志级别

spec.main

用于配置Containerd的主配置文件 (/etc/containerd/config.toml)。

参数	类型	是否必选	描述
`SandboxImage`	`string`	否	Pod 沙箱镜像 (如：pause镜像)
`Root`	`string`	否	Containerd数据根目录，默认为`/var/lib/containerd`
`State`	`string`	否	Containerd状态目录，默认为`/run/containerd`
`ConfigPath`	`string`	否	配置文件路径，默认为`/etc/containerd/certs.d`
`MetricsAddress`	`string`	否	指标监听地址

说明：
如果指定了main字段，系统会根据模板生成config.toml文件。如果未指定，则使用默认配置。

spec.registry

用于配置镜像仓库的 hosts.toml文件。

参数	类型	是否必选	描述
`ConfigPath`	`string`	否	hosts.toml配置目录，默认为`/etc/containerd/certs.d`
`Configs`	`map[string]RegistryHostConfig`	是	仓库配置映射，键为仓库名称

RegistryHostConfig字段：

参数	类型	是否必选	描述
`Host`	`string`	是	仓库主机地址
`Capabilities`	`[]string`	否	支持的能力(如：pull，push，resolve)
`SkipVerify`	`bool`	否	跳过TLS验证
`PlainHTTP`	`bool`	否	使用HTTP而非HTTPS
`Insecure`	`bool`	否	不安全连接
`OverridePath`	`bool`	否	覆盖路径
`TLS`	`TLSConfig`	否	TLS配置
`Auth`	`RegistryAuthConfig`	否	认证配置
`Header`	`map[string][]string`	否	自定义HTTP头

TLSConfig字段：

参数	类型	是否必选	描述
`CAFile`	`string`	否	CA证书文件路径
`CertFile`	`string`	否	客户端证书文件路径
`KeyFile`	`string`	否	客户端私钥文件路径
`InsecureSkipVerify`	`bool`	否	跳过TLS验证

RegistryAuthConfig字段：

参数	类型	是否必选	描述
`Auth`	`string`	否	Base64编码的认证字符串
`Username`	`string`	否	用户名
`Password`	`string`	否	密码
`IdentityToken`	`string`	否	身份令牌
`RegistryToken`	`string`	否	仓库令牌