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:

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

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.

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

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

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

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

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

List available charts and versions:
```
helm search repo karmada
```

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

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

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

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
  
}'

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

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...
    }
  }
}'

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.

Regular Upgrading Process​

Upgrading APIs​

Manual Upgrade API​

Upgrading Components​

Upgrade Support​

Helm Upgrade​

Configuration Changes​

Version Update​

Local Update​

Remote Update​

Operator Upgrade​

Configuration Changes​

Version Update​

Regular Upgrading Process

Upgrading APIs

Manual Upgrade API

Upgrading Components

Upgrade Support

Helm Upgrade

Configuration Changes

Version Update

Local Update

Remote Update

Operator Upgrade

Configuration Changes

Version Update