使用karmadactl init自定义组件命令行参数

概述

karmadactl init 命令用于在 Kubernetes 集群中安装 Karmada 控制面组件。为了提高用户的可定制性，该命令支持在安装过程中自定义组件命令行参数。组件命令行参数是传递给可执行文件的参数，用于控制组件的行为、配置运行环境或指定特定的操作模式，可以影响日志级别、监听端口、性能调优选项等多个方面。

本文档将详细介绍 karmadactl init 命令自定义 Karmada 控制平面的两种方式：命令参数和配置文件。

如何自定义组件命令行参数

默认组件命令行参数

在开始自定义控制平面之前，了解各组件的默认命令行参数至关重要。这有助于确定需要传递哪些自定义参数。

Etcd

  containers:
  - command:
    - /usr/local/bin/etcd
    - --name=$(POD_NAME)
    - --listen-peer-urls=http://$(POD_IP):2380
    - --listen-client-urls=https://$(POD_IP):2379,http://127.0.0.1:2379
    - --advertise-client-urls=https://$(POD_NAME).etcd.karmada-system.svc.cluster.local:2379
    - --initial-cluster=etcd-0=http://etcd-0.etcd.karmada-system.svc.cluster.local:2380
    - --initial-cluster-state=new
    - --client-cert-auth=true
    - --cert-file=/etc/karmada/pki/etcd-server.crt
    - --key-file=/etc/karmada/pki/etcd-server.key
    - --trusted-ca-file=/etc/karmada/pki/etcd-ca.crt
    - --data-dir=/var/lib/karmada-etcd
    - --snapshot-count=10000
    - --cipher-suites=TLS_AES_128_GCM_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
    - --initial-cluster-token=etcd-cluster
    - --initial-advertise-peer-urls=http://$(POD_IP):2380
    - --peer-client-cert-auth=false
    - --peer-trusted-ca-file=/etc/karmada/pki/etcd-ca.crt
    - --peer-key-file=/etc/karmada/pki/etcd-server.key
    - --peer-cert-file=/etc/karmada/pki/etcd-server.crt

其中的环境变量为：

env:
- name: POD_NAME
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: metadata.name
- name: POD_IP
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: status.podIP

karmadaAPIServer

  containers:
  - command:
    - kube-apiserver
    - --allow-privileged=true
    - --authorization-mode=Node,RBAC
    - --client-ca-file=/etc/karmada/pki/ca.crt
    - --enable-bootstrap-token-auth=true
    - --etcd-cafile=/etc/karmada/pki/etcd-ca.crt
    - --etcd-certfile=/etc/karmada/pki/etcd-client.crt
    - --etcd-keyfile=/etc/karmada/pki/etcd-client.key
    - --etcd-servers=https://etcd-0.etcd.karmada-system.svc.cluster.local:2379
    - --bind-address=0.0.0.0
    - --disable-admission-plugins=StorageObjectInUseProtection,ServiceAccount
    - --runtime-config=
    - --apiserver-count=1
    - --secure-port=5443
    - --service-account-issuer=https://kubernetes.default.svc.cluster.local
    - --service-account-key-file=/etc/karmada/pki/karmada.key
    - --service-account-signing-key-file=/etc/karmada/pki/karmada.key
    - --service-cluster-ip-range=10.96.0.0/12
    - --proxy-client-cert-file=/etc/karmada/pki/front-proxy-client.crt
    - --proxy-client-key-file=/etc/karmada/pki/front-proxy-client.key
    - --requestheader-allowed-names=front-proxy-client
    - --requestheader-client-ca-file=/etc/karmada/pki/front-proxy-ca.crt
    - --requestheader-extra-headers-prefix=X-Remote-Extra-
    - --requestheader-group-headers=X-Remote-Group
    - --requestheader-username-headers=X-Remote-User
    - --tls-cert-file=/etc/karmada/pki/apiserver.crt
    - --tls-private-key-file=/etc/karmada/pki/apiserver.key
    - --tls-min-version=VersionTLS13

karmadaAggregatedAPIServer

  containers:
  - command:
    - /bin/karmada-aggregated-apiserver
    - --kubeconfig=/etc/karmada/config/karmada.config
    - --authentication-kubeconfig=/etc/karmada/config/karmada.config
    - --authorization-kubeconfig=/etc/karmada/config/karmada.config
    - --etcd-servers=https://etcd-0.etcd.karmada-system.svc.cluster.local:2379
    - --etcd-cafile=/etc/karmada/pki/etcd-ca.crt
    - --etcd-certfile=/etc/karmada/pki/etcd-client.crt
    - --etcd-keyfile=/etc/karmada/pki/etcd-client.key
    - --tls-cert-file=/etc/karmada/pki/karmada.crt
    - --tls-private-key-file=/etc/karmada/pki/karmada.key
    - --tls-min-version=VersionTLS13
    - --audit-log-path=-
    - --audit-log-maxage=0
    - --audit-log-maxbackup=0
    - --bind-address=$(POD_IP)

其中环境变量为：

env:
- name: POD_IP
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: status.podIP

kubeControllerManager

  containers:
  - command:
    - kube-controller-manager
    - --allocate-node-cidrs=true
    - --kubeconfig=/etc/karmada/config/karmada.config
    - --authentication-kubeconfig=/etc/karmada/config/karmada.config
    - --authorization-kubeconfig=/etc/karmada/config/karmada.config
    - --bind-address=0.0.0.0
    - --client-ca-file=/etc/karmada/pki/ca.crt
    - --cluster-cidr=10.244.0.0/16
    - --cluster-name=karmada-apiserver
    - --cluster-signing-cert-file=/etc/karmada/pki/ca.crt
    - --cluster-signing-key-file=/etc/karmada/pki/ca.key
    - --controllers=namespace,garbagecollector,serviceaccount-token,ttl-after-finished,bootstrapsigner,tokencleaner,csrcleaner,csrsigning,clusterrole-aggregation
    - --leader-elect=true
    - --leader-elect-resource-namespace=karmada-system
    - --node-cidr-mask-size=24
    - --root-ca-file=/etc/karmada/pki/ca.crt
    - --service-account-private-key-file=/etc/karmada/pki/karmada.key
    - --service-cluster-ip-range=10.96.0.0/12
    - --use-service-account-credentials=true
    - --v=4

karmadaControllerManager

  containers:
  - command:
    - /bin/karmada-controller-manager
    - --kubeconfig=/etc/karmada/config/karmada.config
    - --metrics-bind-address=$(POD_IP):8080
    - --health-probe-bind-address=$(POD_IP):10357
    - --cluster-status-update-frequency=10s
    - --leader-elect-resource-namespace=karmada-system
    - --v=4

其中环境变量为：

env:
  - name: POD_IP
    valueFrom:
      fieldRef:
        apiVersion: v1
        fieldPath: status.podIP

karmadaScheduler

  containers:
  - command:
    - /bin/karmada-scheduler
    - --kubeconfig=/etc/karmada/config/karmada.config
    - --metrics-bind-address=$(POD_IP):8080
    - --health-probe-bind-address=$(POD_IP):10351
    - --enable-scheduler-estimator=true
    - --leader-elect=true
    - --scheduler-estimator-ca-file=/etc/karmada/pki/ca.crt
    - --scheduler-estimator-cert-file=/etc/karmada/pki/karmada.crt
    - --scheduler-estimator-key-file=/etc/karmada/pki/karmada.key
    - --leader-elect-resource-namespace=karmada-system
    - --v=4

其中环境变量为：

env:
- name: POD_IP
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: status.podIP

karmadaWebhook

  containers:
  - command:
    - /bin/karmada-webhook
    - --kubeconfig=/etc/karmada/config/karmada.config
    - --bind-address=$(POD_IP)
    - --metrics-bind-address=$(POD_IP):8080
    - --health-probe-bind-address=$(POD_IP):8000
    - --secure-port=8443
    - --cert-dir=/var/serving-cert
    - --v=4

其中环境变量为：

env:
- name: POD_IP
  valueFrom:
    fieldRef:
      apiVersion: v1
      fieldPath: status.podIP

命令参数

init 命令开放了多个命令参数来传递用户自定义的组件命令行参数。

参数传递格式

支持两种格式：

1. 逗号分隔格式：一个命令参数对应多个参数值，参数值通过逗号分隔；
2. 多参数格式：一个命令参数对应一个参数值，可设置多次。

组件参数映射

组件	命令参数	官方文档链接
Etcd	--etcd-extra-args	Etcd 配置参数
karmadaAPIServer	--karmada-apiserver-extra-args	karmadaAPIServer 配置参数
karmadaAggregatedAPIServer	--karmada-aggregated-apiserver-extra-args	karmadaAggregatedAPIServer 配置参数
kubeControllerManager	--karmada-kube-controller-manager-extra-args	kubeControllerManager 配置参数
karmadaControllerManager	--karmada-controller-manager-extra-args	karmadaControllerManager 配置参数
karmadaScheduler	--karmada-scheduler-extra-args	karmadaScheduler 配置参数
karmadaWebhook	--karmada-webhook-extra-args	karmadaWebhook 配置参数

版本兼容性：不同版本的组件可能支持不同的命令行参数。请参阅相应组件版本的官方文档。

使用示例：

自定义 Etcd 组件命令行参数

逗号分割格式：

karmadactl init --etcd-extra-args="--snapshot-count=5000,--heartbeat-interval=100"

多参数格式：

karmadactl init --etcd-extra-args="--snapshot-count=5000" --etcd-extra-args="--heartbeat-interval=100"

更多信息请参阅 karmadactl init --help

配置文件

YAML 配置结构

使用 YAML 配置文件可以更加清晰地管理所有组件的配置。配置文件基于 config.karmada.io/v1alpha1 API 版本。 关于详细的配置文件结构和参数描述，请参阅：Karmadactl初始化配置 v1alpha1 文档。

添加 extraArgs 字段

在配置文件的对应组件部分添加 extraArgs 字段来传递额外参数：

Etcd 配置示例

spec:
  etcd:
    local:
      repository: "registry.k8s.io/etcd"
      tag: "latest"
      dataPath: "/var/lib/karmada-etcd"
      initImage:
        repository: "alpine"
        tag: "3.19.1"
      nodeSelectorLabels:
        karmada.io/etcd: "true"
      pvcSize: "5Gi"
      replicas: 3
      storageMode: "PVC"
      extraArgs:
         - name: snapshot-count
           value: "5000"
         - name: heartbeat-interval
           value: "100"

其他组件的配置示例与上述相同。

使用配置文件

将配置保存为 YAML 文件（如 karmada-init.yaml），然后使用 --config 参数：

karmadactl init --config /path/to/karmada-init.yaml

覆盖命令参数

配置文件优先于命令参数。

问题定位

常见问题

1. 参数格式错误

   • 命令行参数名前有双短横线 (--)
   • 使用逗号分隔时，请确保不要使用中文逗号（，），并且多个参数值之间不要有空格。

2. 组件启动失败

   • 查看组件的日志输出
   • 验证传递的参数是否被该组件版本支持

3. 配置文件解析失败

   • 检查 YAML 语法是否正确
   • 确认版本和字段名称是否正确