Skip to main content
Version: v1.14

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