# Upgrading Konvoy (Essential)

< -- will have a "duplicate" but with differing steps for Enterprise, draft here: https://hackmd.io/ZA7mRo5CSfm7i_lfPEr0UQ?view -- >

The Konvoy upgrade encompasses the following three steps:

1. Upgrade the CAPI components
2. Upgrade the core addons
3. Upgrade the Kubernetes version

If you have more than one Essential licenses, run all of these steps on each Essential Cluster (Management or Kommander Cluster).

## Prerequisites

- Ensure that all Platform Applications in the Management Cluster have been upgraded to avoid compatibility issues with the current Kubernetes version. This is done automatically when [upgrading Kommander][upgrade-kommander].
- For air-gapped: Download the required bundles.

## Upgrade the CAPI Components

New versions of DKP can come prebundled with newer versions of [Cluster API](https://cluster-api.sigs.k8s.io/), newer versions of infrastructure providers or new infrastructure providers. When using a new version of the DKP CLI the first thing you should do is upgrade all of these components.

If you are running on more than one Management Cluster (Kubernetes cluster provisioned with DKP), upgrade the CAPI Components on each of these clusters. For this, ensure your `dkp` configuration **references the Management Cluster, where you want to run the upgrade**. You can do this by setting the `KUBECONFIG` environment variable [to the appropriate kubeconfig file's location][k8s_access_to_clusters].

<p class="message--note"><strong>NOTE:</strong> An alternative to initializing the KUBECONFIG environment variable as stated earlier is to use the <code>--kubeconfig=cluster_name.conf</code> flag. This ensures that Kommander upgrades on the workload cluster.</p>

1. Run the following command:

    dkp upgrade capi-components

The output should be similar to:

     ✓ Upgrading CAPI components
     ✓ Waiting for CAPI components to be upgraded
     ✓ Initializing new CAPI components
     ✓ Deleting Outdated Global ClusterResourceSets

You can verify the components were upgraded by comparing the output to (TODO: need to update this output with newest version for the release):

    kubectl get provider --all-namespaces
    NAMESPACE                           NAME                            AGE     TYPE                     PROVIDER         VERSION
    capa-system                         infrastructure-aws              5m54s   InfrastructureProvider   aws              v1.2.0-d2iq.0
    capi-kubeadm-bootstrap-system       bootstrap-kubeadm               6m2s    BootstrapProvider        kubeadm          v1.1.3-d2iq.3
    capi-kubeadm-control-plane-system   control-plane-kubeadm           5m58s   ControlPlaneProvider     kubeadm          v1.1.3-d2iq.3
    capi-system                         cluster-api                     6m5s    CoreProvider             cluster-api      v1.1.3-d2iq.3
    cappp-system                        infrastructure-preprovisioned   5m44s   InfrastructureProvider   preprovisioned   v0.5.0
    capv-system                         infrastructure-vsphere          57s     InfrastructureProvider   vsphere          v1.1.1
    capz-system                         infrastructure-azure            5m47s   InfrastructureProvider   azure                 v1.1.1

If the upgrade fails, ensure you have reviewed the prerequisites section and have followed the steps described in the [DKP upgrade overview][dkp_upgrade].

## Upgrade the core addons

### Before you begin

To install the core addons, DKP relies on the [ClusterResourceSet](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200220-cluster-resource-set.md) Cluster API feature, which you may have noticed in the message `Deleting Outdated Global ClusterResourceSets` when upgrading the CAPI components in a previous step. Prior to DKP 2.2 some addons were installed using a global configuration. To suppport invidual cluster upgrades, DKP 2.2 now installs all addons with a unique set of `ClusterResourceSet` and corresponding referenced resources, all named using the cluster's name as a suffix, eg. `calico-cni-installation-my-aws-cluster` in our example.

**WARNING** If you have modified any of the clusterResourceSet definitions (this is not common), these changes will NOT be preserved when running the command `dkp upgrade addons`. You can use the `--dry-run -o yaml` options to save the new configuration to a file and remake the same changes upon upgrade.

### Upgrade

Your cluster comes preconfigured with a few different core addons, which provide functionality to your cluster upon creation. These include: CSI, CNI, Cluster Autoscaler, and Node Feature Discovery. New versions of DKP may come prebundled with newer versions of these addons. Perform the following steps to update these addons:

1. If you have more than one Essential licenses, ensure your `dkp` configuration **references the cluster, where you want to run the upgrade**. You can do this by setting the `KUBECONFIG` environment variable [to the appropriate kubeconfig file's location][k8s_access_to_clusters]. An alternative to initializing the KUBECONFIG environment variable is to use the ```–kubeconfig=cluster_name.conf``` flag.

1. Replace `my-aws-cluster` with the name of the cluster:

    export CLUSTER_NAME=my-aws-cluster

    dkp upgrade addons aws --cluster-name=${CLUSTER_NAME}

The output should be similar to:

    Generating addon resources
    clusterresourceset.addons.cluster.x-k8s.io/calico-cni-    installation-my-aws-cluster upgraded
    configmap/calico-cni-installation-my-aws-cluster upgraded
    clusterresourceset.addons.cluster.x-k8s.io/tigera-operator-my-aws-cluster upgraded
    configmap/tigera-operator-my-aws-cluster upgraded
    clusterresourceset.addons.cluster.x-k8s.io/aws-ebs-csi-my-aws-cluster upgraded
    configmap/aws-ebs-csi-my-aws-cluster upgraded
    clusterresourceset.addons.cluster.x-k8s.io/cluster-autoscaler-my-aws-cluster upgraded
    configmap/cluster-autoscaler-my-aws-cluster upgraded
    clusterresourceset.addons.cluster.x-k8s.io/node-feature-discovery-my-aws-cluster upgraded
    configmap/node-feature-discovery-my-aws-cluster upgraded
    clusterresourceset.addons.cluster.x-k8s.io/nvidia-feature-discovery-my-aws-cluster upgraded
    configmap/nvidia-feature-discovery-my-aws-cluster upgraded

1. You should now see pods for these addons restarting in your cluster:

## Upgrade the Kubernetes version

There are two steps to upgrading the Kubernetes version of the cluster. First, upgrade the control plane, then the node pools.

Run the below commands:

Replace `my-aws-cluster` with the name of the cluster.

export CLUSTER_NAME=my-aws-cluster

1. Upgrade the Kubernetes version of the control plane.

    dkp update controlplane aws --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.22.8

The output should be similar to:

    TODO

2. Upgrade the Kubernetes version of each of your node pools.

Replace `my-nodepool` with the name of the nodepool.

    export NODEPOOL_NAME=my-nodepool

    dkp update nodepool aws ${NODEPOOL_NAME} --cluster-name=${CLUSTER_NAME} --kubernetes-version=v1.22.8

The output should be similar to:

    TODO

Repeat this step for each additional node pool.

[k8s_access_to_clusters]: https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/
[upgrade-kommander]: ../../upgrade-kommander
[dkp_upgrade]: ../../dkp-upgrade/