版本：v25.12

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

背景信息 ​

本文档介绍如何使用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结构 ​

bash
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.confmap[string]RawExtension是包含raw字段的配置对象
kubelet.conf.rawstring是Kubelet配置文件的完整YAML内容

raw 字段格式：

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

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)。

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

kubeletService 字段说明：

参数类型是否必选描述
ExecStartstring否服务启动命令
Restartstring否重启策略(如：always，on-failure)
RestartSecstring否重启间隔时间(如：5s，10s)
StartLimitIntervalstring否启动限制时间窗口
StartLimitBurstint否启动限制次数
KillModestring否终止模式(如：control-group，process)
StandardOutputstring否标准输出重定向 (如：journal，null)
StandardErrorstring否标准错误重定向
SyslogIdentifierstring否系统日志标识符
WorkingDirectorystring否工作目录
Userstring否运行用户
Groupstring否运行组
ExecStartPre[]string否启动前执行的命令列表
Environment[]string否环境变量列表 (格式：KEY=VALUE)
EnvironmentFile[]string否环境变量文件路径列表
CustomExtramap[string]string否自定义额外配置项(键值对)

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

kubelet动态传值功能

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

启用变量替换

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

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

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

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

语法：

${EXPR|shell_command|END}

示例：

yaml
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

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结构 ​

yaml
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前执行自定义脚本。

参数类型是否必选描述
Contentstring否脚本内容(内联脚本)
Pathstring否脚本文件路径(本地文件)
Interpreterstring否解释器(如：/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)。

参数类型是否必选描述
ExecStartstring否服务启动命令
Slicestring否systemd slice单元
KillModestring否终止模式
Restartstring否重启策略
RestartSecstring否重启间隔时间
TimeoutStopSecstring否停止超时时间
StartLimitIntervalstring否启动限制时间窗口
StartLimitBurstint否启动限制次数
LoggingLoggingConfig否日志配置
CustomExtramap[string]string否自定义额外配置项

LoggingConfig字段：

参数类型是否必选描述
StandardOutputstring否标准输出重定向
StandardErrorstring否标准错误重定向
SyslogIdentifierstring否系统日志标识符
LogLevelMaxstring否最大日志级别

spec.main

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

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

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

spec.registry

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

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

RegistryHostConfig字段：

参数类型是否必选描述
Hoststring是仓库主机地址
Capabilities[]string否支持的能力(如：pull，push，resolve)
SkipVerifybool否跳过TLS验证
PlainHTTPbool否使用HTTP而非HTTPS
Insecurebool否不安全连接
OverridePathbool否覆盖路径
TLSTLSConfig否TLS配置
AuthRegistryAuthConfig否认证配置
Headermap[string][]string否自定义HTTP头

TLSConfig字段：

参数类型是否必选描述
CAFilestring否CA证书文件路径
CertFilestring否客户端证书文件路径
KeyFilestring否客户端私钥文件路径
InsecureSkipVerifybool否跳过TLS验证

RegistryAuthConfig字段：

参数类型是否必选描述
Authstring否Base64编码的认证字符串
Usernamestring否用户名
Passwordstring否密码
IdentityTokenstring否身份令牌
RegistryTokenstring否仓库令牌

遵循 木兰宽松许可证第2版（MulanPSL2）

版权所有 © 2026 openFuyao 保留一切权利ICP备案号：粤A2-20044005号-306粤公网安备44030002007300号
隐私政策法律声明关于cookies
隐私政策法律声明关于cookies
遵循木兰宽松许可证第2版（MulanPSL2）
版权所有 © 2026 openFuyao 保留一切权利
粤公网安备44030002007300号ICP备案号：粤A2-20044005号-306