Skip to main content
Version: Next

How to Upgrade

This guide outlines the process for upgrading Karmada, covering API and component updates, as well as support for upgrade methods like Helm and Operator.

Regular Upgrading Process​

Upgrading APIs​

For releases that introduce API changes, the Karmada API (CRD) that Karmada components rely on must be upgraded to maintain consistency.

Karmada CRD consists of two parts:

  • bases: The CRD definition generated via API structs.
  • patches: Conversion settings for the CRD.

To support multiple versions of custom resources, the patches should be injected into bases. To achieve this, we introduced a kustomization.yaml configuration and use kubectl kustomize to build the final CRD.

The bases, patches, and kustomization.yaml are now located in the charts/_crds directory of the repo.

Manual Upgrade API​

Step 1: Get the Webhook CA certificate

The CA certificate will be injected into patches before building the final CRD. We can retrieve it from the MutatingWebhookConfiguration or ValidatingWebhookConfiguration configurations, e.g:

kubectl get mutatingwebhookconfigurations.admissionregistration.k8s.io mutating-config

Copy the ca_string from the YAML path webhooks.name[x].clientConfig.caBundle, then replace the {{caBundle}} in the YAML files in patches. For example:

sed -i'' -e "s/{{caBundle}}/${ca_string}/g" ./"charts/karmada/_crds/patches/webhook_in_resourcebindings.yaml"
sed -i'' -e "s/{{caBundle}}/${ca_string}/g" ./"charts/karmada/_crds/patches/webhook_in_clusterresourcebindings.yaml"

Step 2: Build the final CRD

Generate the final CRD using the kubectl kustomize command, for example:

kubectl kustomize ./charts/karmada/_crds

Or, you can apply it to karmada-apiserver by:

kubectl kustomize ./charts/karmada/_crds | kubectl apply -f -

Upgrading Components​

Component upgrades involve image version updates and possible command argument changes.

For argument changes, please refer to Details Upgrading Instruction.

Upgrade Support​

To simplify the upgrade process, Karmada provides multiple upgrade support methods, as detailed below:

note

The upgrade methods for Karmada installed via different installation methods may vary. Please select the corresponding upgrade method based on your actual installation method.

Helm Upgrade​

If you installed Karmada using Helm, you can upgrade Karmada using the helm upgrade command.

Configuration Changes​

To adjust component parameters (e.g., feature gates) without changing the software version, modify the configuration file. The specific process is as follows:

  1. First, ensure you have a Karmada cluster installed via helm install, for example:

    helm install karmada -n karmada-system --create-namespace karmada-chart-v1.14.0.tgz

  2. Suppose you want to update the featureGates parameter of karmada-controller-manager to enable the FederatedQuotaEnforcement feature. You can use the following command:

    $ helm upgrade karmada -n karmada-system --create-namespace karmada-chart-v1.14.0.tgz --set controllerManager.featureGates.FederatedQuotaEnforcement=true
    Release "karmada" has been upgraded. Happy Helming!
    NAME: karmada
    LAST DEPLOYED: Mon Jun 23 15:03:51 2025
    NAMESPACE: karmada-system
    STATUS: deployed
    REVISION: 2
    TEST SUITE: None

    In addition to using the --set command-line parameter, you can also update configurations by modifying the values.yaml file.

  3. Verify the update by checking the karmada-controller-manager manifest before and after the update:

    Before update:

            - --feature-gates=PropagateDeps=false

    After update:

            - --feature-gates=FederatedQuotaEnforcement=true,PropagateDeps=false

Version Update​

To update the Karmada version (e.g., from v1.13.0 to v1.14.0), use the following steps:

Local Update​

  1. Start with a Karmada cluster installed via Helm, for example:

    helm install karmada -n karmada-system --create-namespace karmada-chart-v1.13.0.tgz

  2. Prepare the Helm Chart package for v1.14.0 (e.g., karmada-chart-v1.14.0.tgz), then run:

    helm upgrade karmada -n karmada-system --create-namespace karmada-chart-v1.14.0.tgz

    This command triggers the Karmada upgrade process, including API and component upgrades.

Remote Update​

  1. First, add the Karmada chart repository to your local repository:

    $ helm repo add karmada-charts https://raw.githubusercontent.com/karmada-io/karmada/master/charts
    $ helm repo list
    NAME            URL
    karmada-charts   https://raw.githubusercontent.com/karmada-io/karmada/master/charts

  2. List available charts and versions:

    helm search repo karmada

  3. Install or upgrade the chart, specifying the version with the --version argument. Replace <x.x.x> with your target version:

    $ helm --namespace karmada-system upgrade -i karmada karmada-charts/karmada --version=v1.14.0 --create-namespace
    NAME: karmada
    LAST DEPLOYED: Mon Jun 23 16:42:07 2025
    NAMESPACE: karmada-system
    STATUS: deployed
    REVISION: 2
    TEST SUITE: None

Operator Upgrade​

The Karmada Operator manages the lifecycle (installation, upgrade, and uninstallation) of Karmada clusters via Custom Resources (CRs). If you installed Karmada using the Karmada Operator, you can upgrade Karmada by modifying the Karmada CR.

Configuration Changes​

  1. Deploy the Karmada Operator and create a Karmada instance (see the Karmada Operator installation tutorial for details).

  2. Update the Karmada CR to modify component configurations, such as disabling the hpaScaleTargetMarker controller in the controller manager:

    kubectl patch karmada karmada-demo -n test --type merge -p '
    {
      "spec": {
        "components": {
          "karmadaControllerManager": {
            "extraArgs": {
              "controllers": "*,-hpaScaleTargetMarker"
            }
          }
        }
      }
    }'

Version Update​

  1. Suspend reconciliation of the Karmada CR to avoid invalid restarts during the update:

    kubectl patch karmada karmada-demo -n test --type merge -p '
    {
      "spec": {
        "suspend": true
      
    }'

  2. Upgrade the Karmada Operator (typically requires matching the minor version of Karmada components) and update the Karmada API:

    kubectl set image --namespace karmada-system deployments/karmada-operator karmada-operator=docker.io/karmada/karmada-operator:<imageTag>
    kubectl apply -f https://raw.githubusercontent.com/karmada-io/karmada/refs/tags/<imageTag>/charts/karmada-operator/crds/operator.karmada.io_karmadas.yaml

  3. Update the Karmada CR:

    • Upgrade Karmada components by updating the imageTag in the CR.
    • Upgrade the APIs by updating the crdTarball in the CR.
    • Refer to Details Upgrading Instruction to remove deprecated parameters in the new version.
    kubectl patch karmada karmada-demo -n test --type merge -p '
    {
      "spec": {
        "crdTarball": {
          "httpSource": {
            "url": "https://github.com/karmada-io/karmada/releases/download/v1.14.0/crds.tar.gz"
          }
        },
        "components": {
          "karmadaAggregatedAPIServer": {
            "imageTag": "v1.14.0"
          },
          "karmadaControllerManager": {
            "imageTag": "v1.14.0"
          },
          ## Other components omitted for brevity...
        }
      }
    }'

  4. Resume reconciliation of the Karmada CR:

    kubectl patch karmada karmada-demo -n test --type merge -p '
    {
      "spec": {
        "suspend": false
      }
    }'

After completing the above steps, the Karmada upgrade is complete.