Karmadactl Configuration (v1alpha1)

Overview

The karmadactl init command supports loading configuration parameters from a YAML file to simplify the deployment process for Karmada's control plane. This feature allows users to define all the necessary settings in a configuration file, reducing the complexity of managing numerous command-line flags and improving consistency across different environments.

This document explains the structure of the YAML configuration file used with karmadactl init --config, based on the v1alpha1 version of the configuration schema.

YAML Configuration Structure

The configuration file is structured into the following key sections:

apiVersion

Specifies the API version of the configuration file. For Karmada initialization, it should always be config.karmada.io/v1alpha1.

apiVersion: config.karmada.io/v1alpha1

kind

Defines the type of configuration. For Karmada initialization, this value should always be InitConfiguration.

kind: KarmadaInitConfig

spec

Contains the main configuration specifications for initializing Karmada.

certificates

Configures the certificate information required by Karmada components.

• caCertFile: Path to the root CA certificate file. If not specified, a new self-signed CA certificate will be generated.
• caKeyFile: Path to the root CA key file. If not specified, a new self-signed CA key will be generated.
• externalDNS: A list of external DNS names to include in the certificates' Subject Alternative Names (SANs).
• externalIP: A list of external IP addresses to include in the certificates' SANs.
• validityPeriod: The validity period of the certificates, specified in Go duration format (e.g., "8760h0m0s" for one year).

spec:
 certificates:
   caCertFile: "/etc/karmada/pki/ca.crt"
   caKeyFile: "/etc/karmada/pki/ca.key"
   externalDNS:
     - "localhost"
     - "example.com"
   externalIP:
     - "192.168.1.2"
     - "172.16.1.2"
   validityPeriod: "8760h0m0s"

etcd

Configures the Etcd cluster used by Karmada. You can choose between a local Etcd cluster (local) or an external Etcd cluster (external).

local

Defines settings for deploying a local Etcd cluster as part of the Karmada control plane.

• repository: The Docker image repository for the Etcd image.
• tag: The image tag (version) of Etcd.
• dataPath: Filesystem path where Etcd will store its data on the host.
• initImage: Image used for the Etcd init container, typically a lightweight image like Alpine Linux.
• nodeSelectorLabels: Labels used to select the nodes where Etcd pods will be scheduled.
• pvcSize: The size of the PersistentVolumeClaim used by Etcd when storageMode is set to PVC.
• replicas: Number of Etcd replicas to deploy. For high availability, an odd number of replicas is recommended (e.g., 3, 5).
• storageMode: Storage mode for Etcd data. Options are emptyDir, hostPath, or PVC.

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"

external

Configures connection settings for an external Etcd cluster.

• endpoints: List of URLs to the external Etcd servers.
• caFile: Path to the CA certificate file for the external Etcd cluster.
• certFile: Path to the client certificate file for authentication.
• keyFile: Path to the client key file for authentication.
• keyPrefix: Key prefix used in the external Etcd cluster to segregate data.

spec:
  etcd:
    external:
      endpoints:
        - "https://example.com:8443"
      caFile: "/path/to/your/ca.crt"
      certFile: "/path/to/your/cert.crt"
      keyFile: "/path/to/your/key.key"
      keyPrefix: "ext-"

hostCluster

Specifies information about the host Kubernetes cluster where Karmada will be installed.

• apiEndpoint: The API server endpoint of the host cluster.
• kubeconfig: Path to the kubeconfig file used to access the host cluster.
• context: The context name within the kubeconfig file to use.
• domain: The DNS domain of the host cluster (e.g., cluster.local).

spec:
  hostCluster:
    apiEndpoint: "https://kubernetes.example.com"
    kubeconfig: "/root/.kube/config"
    context: "karmada-host"
    domain: "cluster.local"

images

Configures image-related settings for Karmada and Kubernetes components.

• imagePullPolicy: The image pull policy. Options are Always, IfNotPresent, or Never.
• imagePullSecrets: A list of Kubernetes secrets used to authenticate with private image registries.
• kubeImageMirrorCountry: Country code for selecting a Kubernetes image mirror (e.g., cn for China).
• kubeImageRegistry: Custom Docker registry to pull Kubernetes images from.
• kubeImageTag: The tag (version) of the Kubernetes images to use.
• privateRegistry:
  • registry: The address of a private image registry. If specified, all images will be pulled from this registry.

spec:
  images:
    imagePullPolicy: "IfNotPresent"
    imagePullSecrets:
      - "PullSecret1"
      - "PullSecret2"
    kubeImageMirrorCountry: "cn"
    kubeImageRegistry: "registry.cn-hangzhou.aliyuncs.com/google_containers"
    kubeImageTag: "v1.29.6"
    privateRegistry:
      registry: "my.private.registry"

components

Defines configurations for individual Karmada components.

karmadaAPIServer

• repository: Docker image repository for the Karmada API Server.
• tag: Image tag for the Karmada API Server.
• replicas: Number of replicas for the API Server deployment.
• advertiseAddress: The IP address that the API Server will advertise to clients.
• networking:
  • namespace: Kubernetes namespace where the API Server will be deployed.
  • port: The port number on which the API Server will listen.

spec:
  components:
    karmadaAPIServer:
      repository: "karmada/kube-apiserver"
      tag: "v1.29.6"
      replicas: 1
      advertiseAddress: "192.168.1.100"
      networking:
        namespace: "karmada-system"
        port: 32443

karmadaAggregatedAPIServer

• repository: Docker image repository for the Aggregated API Server.
• tag: Image tag for the Aggregated API Server.
• replicas: Number of replicas.

spec:
  components:
    karmadaAggregatedAPIServer:
      repository: "karmada/karmada-aggregated-apiserver"
      tag: "v0.0.0-master"
      replicas: 1

kubeControllerManager

• repository: Docker image repository for the Kube Controller Manager.
• tag: Image tag for the Kube Controller Manager.
• replicas: Number of replicas.

spec:
  components:
    kubeControllerManager:
      repository: "karmada/kube-controller-manager"
      tag: "v1.29.6"
      replicas: 1

karmadaControllerManager

• repository: Docker image repository for the Karmada Controller Manager.
• tag: Image tag for the Karmada Controller Manager.
• replicas: Number of replicas.

spec:
  components:
    karmadaControllerManager:
      repository: "karmada/karmada-controller-manager"
      tag: "v0.0.0-master"
      replicas: 1

karmadaScheduler

• repository: Docker image repository for the Karmada Scheduler.
• tag: Image tag for the Karmada Scheduler.
• replicas: Number of replicas.

spec:
  components:
    karmadaScheduler:
      repository: "karmada/karmada-scheduler"
      tag: "v0.0.0-master"
      replicas: 1

karmadaWebhook

• repository: Docker image repository for the Karmada Webhook.
• tag: Image tag for the Karmada Webhook.
• replicas: Number of replicas.

spec:
  components:
    karmadaWebhook:
      repository: "karmada/karmada-webhook"
      tag: "v0.0.0-master"
      replicas: 1

karmadaDataPath

Specifies the directory on the host where Karmada stores its data, including kubeconfig files, certificates, and CRDs.

spec:
  karmadaDataPath: "/etc/karmada"

karmadaPKIPath

Specifies the directory on the host where Karmada stores its PKI (Public Key Infrastructure) files, such as certificates and keys.

spec:
  karmadaPKIPath: "/etc/karmada/pki"

karmadaCRDs

Specifies the URL or path to the tarball containing Karmada Custom Resource Definitions (CRDs) to be installed.

spec:
  karmadaCRDs: "https://github.com/karmada-io/karmada/releases/download/test/crds.tar.gz"

waitComponentReadyTimeout

Specifies the timeout in seconds for waiting for Karmada components to become ready. A value of 0 means wait indefinitely.

spec:
  waitComponentReadyTimeout: 120

Complete Example Configuration File

Below is a complete example of the structure of the karmada-init.yaml file,

apiVersion: config.karmada.io/v1alpha1
kind: KarmadaInitConfig
spec:
  certificates:
    caCertFile: "/path/to/your/ca.crt"
    caKeyFile: "/path/to/your/ca.key"
    externalDNS:
      - "localhost"
      - "example.com"
    externalIP:
      - "192.168.1.2"
      - "172.16.1.2"
    validityPeriod: "8760h0m0s"
  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"
#    external:
#      endpoints:
#        - "https://example.com:8443"
#      caFile: "/path/to/your/ca.crt"
#      certFile: "/path/to/your/cert.crt"
#      keyFile: "/path/to/your/key.key"
#      keyPrefix: "ext-"
  hostCluster:
    apiEndpoint: "https://kubernetes.example.com"
    kubeconfig: "/root/.kube/config"
    context: "karmada-host"
    domain: "cluster.local"
  images:
    imagePullPolicy: "IfNotPresent"
    imagePullSecrets:
      - "PullSecret1"
      - "PullSecret2"
    kubeImageMirrorCountry: "cn"
    kubeImageRegistry: "registry.cn-hangzhou.aliyuncs.com/google_containers"
    kubeImageTag: "v1.29.6"
    privateRegistry:
      registry: "my.private.registry"
  components:
    karmadaAPIServer:
      repository: "registry.k8s.io/kube-apiserver"
      tag: "v1.30.0"
      replicas: 1
      advertiseAddress: "192.168.1.100"
      networking:
        namespace: "karmada-system"
        port: 32443
    karmadaAggregatedAPIServer:
      repository: "docker.io/karmada/karmada-aggregated-apiserver"
      tag: "v1.10.3"
      replica: 1
    kubeControllerManager:
      repository: "registry.k8s.io/kube-controller-manager"
      tag: "v1.30.0"
      replica: 1
    karmadaControllerManager:
      repository: "docker.io/karmada/karmada-controller-manager"
      tag: "v1.10.3"
      replica: 1
    karmadaScheduler:
      repository: "docker.io/karmada/karmada-scheduler"
      tag: "v1.10.3"
      replica: 1
    karmadaWebhook:
      repository: "docker.io/karmada/karmada-webhook"
      tag: "v1.10.3"
      replica: 1
  karmadaDataPath: "/etc/karmada"
  karmadaPKIPath: "/etc/karmada/pki"
  karmadaCRDs: "https://github.com/karmada-io/karmada/releases/download/test/crds.tar.gz"
  waitComponentReadyTimeout: 120

Using the Configuration File

To use this configuration file with karmadactl init, simply pass the path to the YAML file as an argument to the --config flag:

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

Overriding Configuration File Values

If necessary, command-line flags can still be used in conjunction with the configuration file. The parameters specified via the command line will override those in the configuration file. For example, to override the number of API server replicas, you could use:

karmadactl init --config /path/to/karmada-init.yaml --karmada-apiserver-replicas 5